str:
+ """Finds and replaces references that should be a cross reference in given content.
+
+ This should not convert any references that contain `current_object_name`,
+ i.e. if we're processing docstring for `google.cloud.spanner.v1.services`,
+ references to `google.cloud.spanner.v1.services` should not be convereted
+ to references.
+
+ Args:
+ content: body of content to parse and look for references in
+ current_object_name: the name of the current Python object being processed
+ known_uids: list of uid references to look for
+ ignore_examples: Don't convert references in example content
+ if set to True. False by default.
+
+ Returns:
+ content that has been modified with proper cross references if found.
+ """
+ example_text = "Examples:"
+ words = content.split(" ")
+
+ # Contains a list of words that is not a valid reference or converted
+ # references.
+ processed_words = []
+
+ # TODO(https://github.com/googleapis/sphinx-docfx-yaml/issues/208):
+ # remove this in the future.
+ iam_policy_link = "http://github.com/googleapis/python-grpc-google-iam-v1/blob/8e73b45993f030f521c0169b380d0fbafe66630b/google/iam/v1/iam_policy_pb2_grpc.py"
+ hard_coded_references = {
+ "google.iam.v1.iam_policy_pb2.SetIamPolicyRequest": iam_policy_link + "#L103-L109",
+ "google.iam.v1.iam_policy_pb2.GetIamPolicyRequest": iam_policy_link + "#L111-L118",
+ "google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest": iam_policy_link + "#L120-L131",
+ "google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse": iam_policy_link + "#L120-L131"
+ }
+ known_uids.extend(hard_coded_references.keys())
+
+ # Used to keep track of current position to avoid converting if needed.
+ example_index = len(content)
+ for index, word in enumerate(words):
+ if ignore_examples and example_text in word:
+ example_index = index
+ uid = find_uid_to_convert(
+ word, words, index, known_uids, current_object_name, processed_words, hard_coded_references
+ )
+
+ # If the reference is found after example section, ignore it.
+ if uid and (
+ not ignore_examples or
+ (ignore_examples and index < example_index)
+ ):
+ cross_reference = f"{uid} " \
+ if uid in hard_coded_references else \
+ f"{uid} "
+
+ processed_words.append(word.replace(uid, cross_reference))
+ print(f"Converted {uid} into cross reference in: \n{content}")
+ else:
+ # If cross reference has not been found, add current unchanged content.
+ processed_words.append(word)
+
+ return " ".join(processed_words)
+
+
+def search_cross_references(obj: dict, current_object_name: str, known_uids: list[str]) -> None:
+ """Searches for cross references in the object's data.
+
+ Args:
+ obj (dict): The object's data.
+ current_object_name (str): The name of the current object.
+ known_uids (list[str]): A list of known uids.
+ """
+ if obj.get("summary"):
+ obj["summary"] = convert_cross_references(
+ obj["summary"],
+ current_object_name,
+ known_uids,
+ ignore_examples=True,
+ )
+
+ if obj.get("syntax"):
+ if obj["syntax"].get("parameters"):
+ for param in obj["syntax"]["parameters"]:
+ if param.get("description"):
+ param_description = convert_cross_references(
+ param["description"],
+ current_object_name,
+ known_uids
+ )
+ param["description"] = (
+ markdown_utils.reformat_markdown_to_html(param_description))
+
+ if param.get("id"):
+ param_id = convert_cross_references(
+ param["id"],
+ current_object_name,
+ known_uids
+ )
+ param["id"] = markdown_utils.reformat_markdown_to_html(param_id)
+
+ if param.get("var_type"):
+ param_type = convert_cross_references(
+ param["var_type"],
+ current_object_name,
+ known_uids
+ )
+ param["var_type"] = (
+ markdown_utils.reformat_markdown_to_html(param_type))
+
+ if obj["syntax"].get("exceptions"):
+ for exception in obj["syntax"]["exceptions"]:
+ if exception.get("description"):
+ exception_description = convert_cross_references(
+ exception["description"],
+ current_object_name,
+ known_uids
+ )
+ exception["description"] = (
+ markdown_utils.reformat_markdown_to_html(exception_description))
+
+ if exception.get("var_type"):
+ exception_type = convert_cross_references(
+ exception["var_type"],
+ current_object_name,
+ known_uids
+ )
+ exception["var_type"] = (
+ markdown_utils.reformat_markdown_to_html(exception_type))
+
+ if obj["syntax"].get("returns"):
+ for ret in obj["syntax"]["returns"]:
+ if ret.get("description"):
+ ret_description = convert_cross_references(
+ ret["description"],
+ current_object_name,
+ known_uids
+ )
+ ret["description"] = (
+ markdown_utils.reformat_markdown_to_html(ret_description))
+
+ if ret.get("var_type"):
+ ret_type = convert_cross_references(
+ ret["var_type"],
+ current_object_name,
+ known_uids
+ )
+ ret["var_type"] = markdown_utils.reformat_markdown_to_html(ret_type)
+
+
+ if obj.get("attributes"):
+ for attribute in obj["attributes"]:
+ if attribute.get("description"):
+ attribute_description = convert_cross_references(
+ attribute["description"],
+ current_object_name,
+ known_uids
+ )
+ attribute["description"] = (
+ markdown_utils.reformat_markdown_to_html(attribute_description))
+
+ if attribute.get("id"):
+ attribute_id = convert_cross_references(
+ attribute["id"],
+ current_object_name,
+ known_uids
+ )
+ attribute["id"] = markdown_utils.reformat_markdown_to_html(attribute_id)
+
+ if attribute.get("var_type"):
+ attribute_type = convert_cross_references(
+ attribute["var_type"],
+ current_object_name,
+ known_uids
+ )
+ attribute["var_type"] = (
+ markdown_utils.reformat_markdown_to_html(attribute_type))
+
+
+def merge_markdown_and_package_toc(
+ pkg_toc_yaml: list[_yaml_type_alias],
+ markdown_toc_yaml: _yaml_type_alias,
+ known_uids: set[str],
+) -> tuple[MutableSet[str], list[_yaml_type_alias]]:
+ """
+ Merges the markdown and package table of contents.
+
+ Args:
+ pkg_toc_yaml: table of content for package files.
+ markdown_toc_yaml: table fo content for markdown files.
+
+ Returns:
+ A set of markdown pages that has been added, and the merged table of
+ contents file, with files in the correct position.
+ """
+ def _flatten_toc(
+ toc_yaml_entry: list[_yaml_type_alias],
+ ) -> list[_yaml_type_alias]:
+ """Flattens and retrieves all children within pkg_toc_yaml."""
+ entries = list(toc_yaml_entry)
+ for entry in toc_yaml_entry:
+ if (children := entry.get('items')):
+ entries.extend(_flatten_toc(children))
+ return entries
+
+ added_pages = set()
+
+ pkg_toc_entries = _flatten_toc(pkg_toc_yaml)
+
+ for entry in pkg_toc_entries:
+ entry_name = entry['name'].lower()
+ if entry_name not in markdown_toc_yaml:
+ continue
+
+ markdown_pages_to_add = []
+ for page in markdown_toc_yaml[entry_name]:
+ if page['href'].split('.')[0] not in known_uids and (
+ page['href'] not in added_pages):
+ markdown_pages_to_add.append(
+ {'name': page['name'], 'href': page['href']}
+ )
+
+ if not markdown_pages_to_add:
+ continue
+
+ markdown_pages_to_add = sorted(
+ markdown_pages_to_add,
+ key=lambda entry: entry['href'])
+
+ entry['items'] = markdown_pages_to_add + entry['items']
+ added_pages.update({
+ page['href'] for page in markdown_pages_to_add
+ })
+
+ if (top_level_pages := markdown_toc_yaml.get('/')) is None or (
+ top_level_pages and top_level_pages[0]['href'] != 'index.md'):
+ return added_pages, [pkg_toc_yaml]
+
+ added_pages.update({
+ page['href'] for page in top_level_pages
+ })
+
+ return added_pages, top_level_pages + pkg_toc_yaml
+
+
+def build_finished(app: sphinx.application.Sphinx, exception: Exception) -> None:
+ """Builds the finished YAML files.
+
+ Args:
+ app (object): The Sphinx application object.
+ exception (Exception): The exception that was thrown, if any.
+ """
+
+ # Used to get rid of the uidname field for cleaner toc file.
+ def sanitize_uidname_field(pkg_toc_yaml):
+ for module in pkg_toc_yaml:
+ if 'items' in module:
+ sanitize_uidname_field(module['items'])
+ module.pop('uidname')
+
+ def find_node_in_toc_tree(pkg_toc_yaml, to_add_node):
+ for module in pkg_toc_yaml:
+ if module['uidname'] == to_add_node:
+ return module
+
+ if 'items' in module:
+ items = module['items']
+ found_module = find_node_in_toc_tree(items, to_add_node)
+ if found_module != None:
+ return found_module
+ return None
+
+ def convert_module_to_package_if_needed(obj):
+ if 'source' in obj and 'path' in obj['source'] and obj['source']['path']:
+ if obj['source']['path'].endswith(INITPY):
+ obj['type'] = 'subPackage'
+ product_name = extract_product_name(obj['fullName'])
+ obj['summary'] = f"API documentation for `{product_name}` package."
+ return
+
+ for child_uid in obj['children']:
+ if child_uid in app.env.docfx_info_uid_types:
+ child_uid_type = app.env.docfx_info_uid_types[child_uid]
+
+ if child_uid_type == MODULE:
+ obj['type'] = 'package'
+ return
+
+
+ normalized_outdir = os.path.normpath(os.path.join(
+ app.builder.outdir, # Output Directory for Builder
+ API_ROOT,
+ ))
+ ensuredir(normalized_outdir)
+
+ # Add markdown pages to the configured output directory.
+ markdown_utils.move_markdown_pages(app, normalized_outdir)
+
+ pkg_toc_yaml = []
+ # Used to record filenames dumped to avoid confliction
+ # caused by Windows case insensitive file system
+ file_name_set = set()
+
+ # Used to disambiguate entry names
+ yaml_map = {}
+
+ # Order matters here, we need modules before lower level classes,
+ # so that we can make sure to inject the TOC properly
+ for data_set in (app.env.docfx_yaml_modules,
+ app.env.docfx_yaml_classes,
+ app.env.docfx_yaml_functions): # noqa
+
+ for uid, yaml_data in iter(sorted(data_set.items())):
+ if not uid:
+ # Skip objects without a module
+ continue
+
+ references = []
+
+ # Merge module data with class data
+ for obj in yaml_data:
+ arg_params = obj.get('syntax', {}).get('parameters', [])
+ if(len(arg_params) > 0 and 'id' in arg_params[0] and arg_params[0]['id'] == 'self'):
+ # Support having `self` as an arg param, but not documented
+ arg_params = arg_params[1:]
+ obj['syntax']['parameters'] = arg_params
+ if obj['uid'] in app.env.docfx_info_field_data and \
+ obj['type'] == app.env.docfx_info_field_data[obj['uid']]['type']:
+ # Avoid entities with same uid and diff type.
+ del(app.env.docfx_info_field_data[obj['uid']]['type']) # Delete `type` temporarily
+ if 'syntax' not in obj:
+ obj['syntax'] = {}
+ merged_params = []
+ if 'parameters' in app.env.docfx_info_field_data[obj['uid']]:
+ doc_params = app.env.docfx_info_field_data[obj['uid']].get('parameters', [])
+ if arg_params and doc_params:
+ if len(arg_params) - len(doc_params) > 0:
+ app.warn(
+ "Documented params don't match size of params:"
+ " {}".format(obj['uid']))
+ # Zip 2 param lists until the long one is exhausted
+ for args, docs in zip_longest(arg_params, doc_params, fillvalue={}):
+ if len(args) == 0:
+ merged_params.append(docs)
+ else:
+ args.update(docs)
+ merged_params.append(args)
+ obj['syntax'].update(app.env.docfx_info_field_data[obj['uid']])
+ if merged_params:
+ obj['syntax']['parameters'] = merged_params
+
+ if 'parameters' in obj['syntax'] and obj['type'] == 'method':
+ for args in obj['syntax']['parameters']:
+ if 'isRequired' not in args and 'defaultValue' not in args:
+ args['isRequired'] = True
+
+ # Raise up summary
+ if 'summary' in obj['syntax'] and obj['syntax']['summary']:
+ obj['summary'] = obj['syntax'].pop('summary').strip(" \n\r\r")
+
+ # Raise up remarks
+ if 'remarks' in obj['syntax'] and obj['syntax']['remarks']:
+ obj['remarks'] = obj['syntax'].pop('remarks')
+
+ # Raise up seealso
+ if 'seealso' in obj['syntax'] and obj['syntax']['seealso']:
+ obj['seealsoContent'] = obj['syntax'].pop('seealso')
+
+ # Raise up example
+ if 'example' in obj['syntax'] and obj['syntax']['example']:
+ obj.setdefault('example', []).append(obj['syntax'].pop('example'))
+
+ # Raise up exceptions
+ if 'exceptions' in obj['syntax'] and obj['syntax']['exceptions']:
+ obj['exceptions'] = obj['syntax'].pop('exceptions')
+
+ # Raise up references
+ if 'references' in obj['syntax'] and obj['syntax']['references']:
+ obj.setdefault('references', []).extend(obj['syntax'].pop('references'))
+
+ # add content of temp list 'added_attribute' to children and yaml_data
+ if 'added_attribute' in obj['syntax'] and obj['syntax']['added_attribute']:
+ added_attribute = obj['syntax'].pop('added_attribute')
+ for attrData in added_attribute:
+ existed_Data = next((n for n in yaml_data if n['uid'] == attrData['uid']), None)
+ if existed_Data:
+ # Update data for already existed one which has attribute comment in source file
+ existed_Data.update(attrData)
+ else:
+ obj.get('children', []).append(attrData['uid'])
+ yaml_data.append(attrData)
+ if 'class' in attrData:
+ # Get parent for attrData of Non enum class
+ parent = attrData['class']
+ else:
+ # Get parent for attrData of enum class
+ parent = attrData['parent']
+ obj['references'].append(_create_reference(attrData, parent))
+ app.env.docfx_info_field_data[obj['uid']]['type'] = obj['type'] # Revert `type` for other objects to use
+
+ if 'references' in obj:
+ # Ensure that references have no duplicate ref
+ ref_uids = [r['uid'] for r in references]
+ for ref_obj in obj['references']:
+ if ref_obj['uid'] not in ref_uids:
+ references.append(ref_obj)
+ obj.pop('references')
+
+ if obj['type'] == 'module':
+ convert_module_to_package_if_needed(obj)
+
+ if obj['type'] == 'method':
+ # Update the name to use shorter name to show
+ obj['name'] = obj['source']['id']
+
+ # To distinguish distribution package and import package
+ if obj.get('type', '') == 'package' and obj.get('kind', '') != 'distribution':
+ obj['kind'] = 'import'
+
+ # Extract any missing cross references where applicable.
+ # Potential targets are instances of full uid shown, or
+ # if we find a short form of the uid of one of current
+ # package's items. For example:
+ # cross reference candidates:
+ # google.cloud.bigquery_storage_v1.types.storage.SplitReadStreamResponse
+ # SplitReadStreamResponse
+ # non-candidates:
+ # (not from the same library)
+ # google.cloud.aiplatform.AutoMLForecastingTrainingJob
+
+ current_object_name = obj["fullName"]
+ known_uids = sorted(app.env.docfx_uid_names.keys(), reverse=True)
+ # Currently we only need to look in summary, syntax and
+ # attributes for cross references.
+ search_cross_references(obj, current_object_name, known_uids)
+
+ yaml_map[uid] = [yaml_data, references]
+
+ # Parse the name of the object.
+ # Some types will need additional parsing to de-duplicate their names and contain
+ # a portion of their parent name for better disambiguation. This is done in
+ # disambiguate_toc_name
+
+ node_name = uid.split(".")[-1]
+
+ # Build nested TOC
+ if uid.count('.') >= 1:
+ parent_level = '.'.join(uid.split('.')[:-1])
+ found_node = find_node_in_toc_tree(pkg_toc_yaml, parent_level)
+
+ if found_node:
+ found_node.setdefault(
+ 'items',
+ [{'name': 'Overview', 'uidname': parent_level, 'uid': parent_level}]
+ ).append({
+ 'name': node_name,
+ 'uidname': uid,
+ 'uid': uid
+ })
+ else:
+ pkg_toc_yaml.append({
+ 'name': node_name,
+ 'uidname': uid,
+ 'uid': uid
+ })
+
+ else:
+ pkg_toc_yaml.append({
+ 'name': node_name,
+ 'uidname': uid,
+ 'uid': uid
+ })
+
+ # Exit if there are no generated YAML pages or Markdown pages.
+ if len(pkg_toc_yaml) == 0 and len(app.env.markdown_pages) == 0:
+ raise RuntimeError("No documentation for this module.")
+
+ pkg_toc_yaml = group_by_package(pkg_toc_yaml)
+
+ # Perform additional disambiguation of the name
+ disambiguated_names = disambiguate_toc_name(pkg_toc_yaml)
+
+ # Keeping uidname field carrys over onto the toc.yaml files, we need to
+ # be keep using them but don't need them in the actual file
+ pkg_toc_yaml_with_uid = copy.deepcopy(pkg_toc_yaml)
+
+ sanitize_uidname_field(pkg_toc_yaml)
+
+ known_uids = {
+ uid.split('.')[-1]
+ for uid in app.env.docfx_uid_names
+ }
+
+ added_pages, pkg_toc_yaml = merge_markdown_and_package_toc(
+ pkg_toc_yaml, app.env.markdown_pages, known_uids)
+
+ # Remove unused pages after merging the table of contents.
+ if added_pages:
+ markdown_utils.remove_unused_pages(
+ added_pages, app.env.moved_markdown_pages, normalized_outdir)
+
+ if app.env.library_shortname:
+ # Add summary pages as the second entry into the table of contents.
+ pkg_toc_yaml.insert(
+ 1,
+ {
+ "name": f"{app.env.library_shortname} APIs",
+ "items": [
+ {"name": "API overview", "href": "summary_overview.md"},
+ {"name": "Classes", "href": "summary_class.yml"},
+ {"name": "Methods", "href": "summary_method.yml"},
+ {"name": "Properties and Attributes", "href": "summary_property.yml"},
+ ],
+ }
+ )
+
+ toc_file = os.path.join(normalized_outdir, 'toc.yml')
+ with open(toc_file, 'w') as writable:
+ writable.write(
+ dump(
+ [{
+ 'name': app.config.project,
+ 'items': pkg_toc_yaml
+ }],
+ default_flow_style=False,
+ )
+ )
+
+ cgc_url = (
+ "https://cloud.google.com/python/docs/reference/"
+ f"{app.env.library_shortname}/latest/"
+ )
+ yaml_entry_line = "### YamlMime:UniversalReference\n"
+ # Output files
+ for uid, data in iter(yaml_map.items()):
+
+ for yaml_item in data:
+ for obj in yaml_item:
+ # If the entry was disambiguated, update here:
+ obj_full_name = obj['fullName']
+ if disambiguated_names.get(obj_full_name):
+ obj['name'] = disambiguated_names[obj_full_name]
+ if obj['type'] == 'subPackage':
+ obj['summary'] = "API documentation for `{}` package.".format(obj['name'])
+
+ # data is formatted as [yaml_data, references]
+ yaml_data, references = data
+
+ if uid.lower() in file_name_set:
+ filename = uid + "(%s)" % app.env.docfx_info_uid_types[uid]
+ else:
+ filename = uid
+
+ out_file = os.path.join(normalized_outdir, '%s.yml' % filename)
+ ensuredir(os.path.dirname(out_file))
+ if app.verbosity >= 1:
+ app.info(bold('[docfx_yaml] ') + darkgreen('Outputting %s' % filename))
+
+ with open(out_file, 'w') as out_file_obj:
+ out_file_obj.write(yaml_entry_line)
+ try:
+ dump(
+ {
+ 'items': yaml_data,
+ 'references': references,
+ 'api_name': [], # Hack around docfx YAML
+ },
+ out_file_obj,
+ default_flow_style=False
+ )
+ except Exception as e:
+ raise ValueError("Unable to dump object\n{0}".format(yaml_data)) from e
+
+ file_name_set.add(filename)
+
+ for entry in yaml_data:
+ if not app.env.library_shortname:
+ break
+ summary_type = _SUMMARY_TYPE_BY_ITEM_TYPE.get(entry.get("type"))
+ if not (summary_type):
+ continue
+
+ _find_and_add_summary_details(entry, summary_type, cgc_url)
+
+ for summary_type in _ENTRY_NAME_AND_ENTRY_CONTENT_BY_SUMMARY_TYPE:
+ children_names_and_content = (
+ _ENTRY_NAME_AND_ENTRY_CONTENT_BY_SUMMARY_TYPE[summary_type]
+ )
+ if not all(children_names_and_content):
+ continue
+
+ file_name, entry_name = _FILE_NAME_AND_ENTRY_NAME_BY_SUMMARY_TYPE[summary_type]
+
+ dump_content = _render_summary_content(
+ children_names_and_content,
+ entry_name,
+ summary_type,
+ app.env.library_shortname,
+ )
+
+ file_path_to_use = os.path.join(normalized_outdir, file_name)
+ with open(file_path_to_use, "w") as summary_file_obj:
+ summary_file_obj.write(yaml_entry_line)
+ dump(
+ dump_content,
+ summary_file_obj,
+ default_flow_style=False,
+ )
+
+
+ index_file = os.path.join(normalized_outdir, 'index.yml')
+ index_children = []
+ index_references = []
+ for package in pkg_toc_yaml_with_uid:
+ for item in package.get("items"):
+ index_children.append(item.get('uidname', ''))
+ index_references.append({
+ 'uid': item.get('uidname', ''),
+ 'name': item.get('name', ''),
+ 'fullname': item.get('uidname', ''),
+ 'isExternal': False
+ })
+
+ '''
+ # TODO: handle xref for other products.
+ xref_file = os.path.join(normalized_outdir, 'xrefs.yml')
+ with open(xref_file, 'w') as xref_file_obj:
+ for xref in app.env.docfx_xrefs:
+ xref_file_obj.write(f'{xref}\n')
+ '''
+
+def missing_reference(app: sphinx.application.Sphinx, env: Any, node: Any, contnode: Any) -> Any:
+ """Called when a reference is missing.
+
+ Args:
+ app (sphinx.application.Sphinx): The sphinx application.
+ env (Any): The environment.
+ node (Any): The node.
+ contnode (Any): The contnode.
+
+ Returns:
+ Any: The new node.
+ """
+ reftarget = ''
+ refdoc = ''
+ reftype = ''
+ module = ''
+ if 'refdomain' in node.attributes and node.attributes['refdomain'] == 'py':
+ reftarget = node['reftarget']
+ reftype = node['reftype']
+ if 'refdoc' in node:
+ refdoc = node['refdoc']
+ if 'py:module' in node:
+ module = node['py:module']
+
+ #Refactor reftarget to fullname if it is a short name
+ if reftype in [CLASS, REFFUNCTION, REFMETHOD] and module and '.' not in reftarget:
+ if reftype in [CLASS, REFFUNCTION]:
+ fields = (module, reftarget)
+ else:
+ fields = (module, node['py:class'], reftarget)
+ reftarget = '.'.join(field for field in fields if field is not None)
+
+ return make_refnode(app.builder, refdoc, reftarget, '', contnode)
+
+
+def setup(app: sphinx.application.Sphinx) -> None:
+ """
+ Plugin init for our Sphinx extension.
+
+ Args:
+ app (Application): The Sphinx application instance
+
+ """
+
+ app.setup_extension('sphinx.ext.autodoc')
+ app.connect('autodoc-process-docstring', _process_docstring)
+
+ app.add_node(remarks, html = (remarks.visit_remarks, remarks.depart_remarks))
+ app.add_directive('remarks', RemarksDirective)
+ app.add_directive('todo', TodoDirective)
+
+ app.connect('builder-inited', build_init)
+ app.connect('autodoc-process-docstring', process_docstring)
+ app.connect('autodoc-process-signature', process_signature)
+ app.connect('build-finished', build_finished)
+ app.connect('missing-reference', missing_reference)
+ app.add_config_value('docfx_yaml_output', API_ROOT, 'html')
+ app.add_config_value('folder', '', 'html')
+ app.add_config_value('autodoc_functions', False, 'env')
diff --git a/packages/gcp-sphinx-docfx-yaml/docfx_yaml/extract_nodes.py b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/extract_nodes.py
new file mode 100644
index 000000000000..c2cae7bad8a8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/extract_nodes.py
@@ -0,0 +1,202 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+**DEPRECATED**
+
+This was an approach that pulls domain data from doctree.
+
+This approach will work for non-autodoc domains.
+However,
+the approach used in this extension is easiest for autodoc.
+
+In order to build the approach going forward,
+a bit more work needs to be done to pull docstrings in raw format.
+"""
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.util.console import bold, red
+from sphinx.util.docfields import _is_single_paragraph
+from sphinx import addnodes
+from .utils import _get_desc_data
+
+TITLE_MAP = {
+ 'Returns': 'return',
+ 'Return type': 'return_type',
+ 'Raises': 'raises',
+ 'Parameters': 'params',
+}
+
+
+def doctree_resolved(app: Sphinx, doctree: nodes.document, docname: str) -> None:
+ """
+ Render out the YAML from the Sphinx domain objects
+
+ Args:
+ app (Sphinx): The sphinx application.
+ doctree (nodes.document): The doctree.
+ docname (str): The name of the document.
+ """
+ yaml_data, yaml_modules = extract_yaml(app, doctree, ignore_patterns=None)
+ extract_info_lists(app, doctree)
+ # if yaml_data:
+ # app.env.docfx_yaml_data[docname] = yaml_data
+ # if yaml_modules:
+ # for module in yaml_modules:
+ # app.env.docfx_yaml_modules[module] = yaml_modules[module]
+
+
+def _get_full_data(node: nodes.Node) -> dict:
+ """Extracts data from a field list node.
+
+ Args:
+ node (nodes.Node): The field list node.
+
+ Returns:
+ dict: The extracted data.
+ """
+ data = {}
+ parent_desc = node.parent.parent
+ name, uid = _get_desc_data(parent_desc)
+ if not name:
+ return
+
+ for field in node:
+ fieldname, fieldbody = field
+ try:
+ # split into field type and argument
+ fieldtype, _ = fieldname.astext().split(None, 1)
+ except ValueError:
+ # maybe an argument-less field type?
+ fieldtype = fieldname.astext()
+
+ # collect the content, trying not to keep unnecessary paragraphs
+ if _is_single_paragraph(fieldbody):
+ content = fieldbody.children[0].children
+ else:
+ content = fieldbody.children
+
+ data.setdefault(uid, {})
+
+ if fieldtype == 'Returns':
+ for child in content:
+ ret_data = child.astext()
+ data[uid].setdefault(fieldtype, []).append(ret_data)
+
+ if fieldtype == 'Raises':
+ for child in content:
+ ret_data = child.astext()
+ data[uid].setdefault(fieldtype, []).append(ret_data)
+ return data
+
+
+def extract_info_lists(app: Sphinx, doctree: nodes.document) -> None:
+ """Extracts info lists from the doctree.
+
+ Args:
+ app (Sphinx): The sphinx application.
+ doctree (nodes.document): The doctree.
+ """
+ data = []
+
+ for node in doctree.traverse(nodes.field_list):
+ data.append(_get_full_data(node))
+
+ print(data)
+
+
+def extract_yaml(app: Sphinx, doctree: nodes.document, ignore_patterns: list[str]) -> tuple[list[dict], dict]:
+ """Iterate over all Python domain objects and output YAML.
+
+ Args:
+ app (Sphinx): The sphinx application.
+ doctree (nodes.document): The doctree.
+ ignore_patterns (list[str]): A list of patterns to ignore.
+
+ Returns:
+ tuple[list[dict], dict]: A tuple containing the list of items and
+ a dictionary of modules.
+ """
+ items = []
+ modules = {}
+
+ for desc_node in doctree.traverse(addnodes.desc):
+ if desc_node.attributes['domain'] != 'py':
+ app.info(bold('[docfx_yaml] ') + red(
+ 'Skipping Domain Object (%s)' % desc_node.attributes['domain']
+ ))
+ continue
+
+ module = desc_node[0].attributes['module']
+
+ if not module:
+ app.info(bold('[docfx_yaml] ') + red(
+ 'Skipping object with no module'
+ ))
+ continue
+
+ if module not in modules:
+ modules[module] = [{
+ 'module': str(module),
+ 'uid': str(module),
+ 'type': 'Namespace',
+ 'type': 'module',
+ 'name': str(module),
+ 'children': []
+ }]
+
+ _type = desc_node.attributes['objtype']
+ full_name = desc_node[0].attributes['fullname']
+ try:
+ uid = desc_node[0].attributes['ids'][0]
+ except Exception:
+ uid = f'{module}.{full_name}'
+ print('Non-standard id: %s' % uid)
+ name = desc_node[0].attributes['names'][0]
+ source = desc_node[0].source
+ try:
+ summary = desc_node[1][0].astext()
+ except (KeyError, IndexError):
+ summary = ''
+
+ try:
+ args = [arg.strip() for arg in desc_node[0][3].astext().split(',')]
+ except Exception:
+ args = []
+
+ if args:
+ full_name += f"({', '.join(args)})"
+
+ datam = {
+ 'module': str(module),
+ 'uid': uid,
+ 'type': _type,
+ 'name': name,
+ 'fullName': full_name,
+ 'summary': summary,
+ 'rst_source': source,
+ }
+
+ if _type == 'method':
+ datam['class'] = '.'.join(name.split('.')[:-1])
+ if _type == 'class':
+ datam['children'] = []
+
+ # insert_children(_type, datam, modules)
+ items.append(datam)
+
+ modules[module].append(datam)
+
+ return (items, modules)
diff --git a/packages/gcp-sphinx-docfx-yaml/docfx_yaml/markdown_utils.py b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/markdown_utils.py
new file mode 100644
index 000000000000..50b1284219e7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/markdown_utils.py
@@ -0,0 +1,538 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -*- coding: utf-8 -*-
+"""Markdown related utilities for Sphinx DocFX YAML extension."""
+
+
+from collections.abc import MutableSet
+import os
+from pathlib import Path
+import re
+import shutil
+from typing import Iterable
+
+from docuploader import shell
+import sphinx.application
+
+
+def _reformat_codeblocks(content: str) -> str:
+ """Formats codeblocks from ``` to .
+
+ Args:
+ content (str): The string to reformat.
+
+ Returns:
+ str: The reformatted string.
+ """
+ triple_backtick = '```'
+ current_tag = ''
+ next_tag = ' '
+ # If there are no proper pairs of triple backticks, don't format docstring.
+ if content.count(triple_backtick) % 2 != 0:
+ print(f'Docstring is not formatted well, missing proper pairs of triple backticks (```): {content}')
+ return content
+ while triple_backtick in content:
+ content = content.replace(triple_backtick, current_tag, 1)
+ # Alternate between replacing with and .
+ current_tag, next_tag = next_tag, current_tag
+
+ return content
+
+
+def _reformat_code(content: str) -> str:
+ """Formats code from ` to .
+
+ Args:
+ content (str): The string to reformat.
+
+ Returns:
+ str: The reformatted string.
+ """
+ reformatted_lines = []
+
+ code_pattern = '`[^`\n]+`'
+ code_start = ''
+ code_end = ''
+ prev_start = prev_end = 0
+ # Convert `text` to text
+ for matched_obj in re.finditer(code_pattern, content):
+ start = matched_obj.start()
+ end = matched_obj.end()
+ code_content = content[start+1:end-1]
+
+ reformatted_lines.append(content[prev_end:start])
+ reformatted_lines.append(f'{code_start}{code_content}{code_end}')
+ prev_start, prev_end = start, end
+
+ reformatted_lines.append(content[prev_end:])
+
+ return ''.join(reformatted_lines)
+
+
+def reformat_markdown_to_html(content: str) -> str:
+ """Applies changes from markdown syntax to equivalent HTML.
+
+ Acts as a wrapper function to format all Markdown to HTML.
+
+ Markdown syntax cannot be used within HTML elements, and must be converted
+ at YAML level.
+
+ Args:
+ content: the string to be reformatted.
+
+ Returns:
+ Content that has been formatted with proper HTML.
+ """
+
+ content = _reformat_codeblocks(content)
+ content = _reformat_code(content)
+
+ return content
+
+
+def _parse_markdown_header(current_line: str, prev_line: str) -> str:
+ """Parses the H1 markdown header if found.
+
+ Args:
+ current_line: line of markdown text to inspect.
+ prev_line: previous line to use if we found line divider for H1.
+
+ Returns:
+ Header for the markdown file if valid header is found.
+ """
+ # Markdown h1 prefix should have only 1 of '#' character followed by exactly one space.
+ h1_header_prefix = "# "
+ if h1_header_prefix in current_line and current_line.count("#") == 1:
+ # Check for proper h1 header formatting, ensure there's more than just
+ # the hashtag character, and exactly only one space after the hashtag.
+ if not current_line[current_line.index(h1_header_prefix)+2].isspace() and \
+ len(current_line) > 2:
+
+ return current_line[current_line.index(h1_header_prefix):].strip("#").strip()
+
+ elif "=" in current_line:
+ # Check if we're inspecting an empty or undefined lines.
+ if not prev_line:
+ return ""
+
+ # Check if the current line only has equal sign divider.
+ if current_line.count("=") == len(current_line.strip()):
+ # Update header to the previous line.
+ return prev_line.strip()
+
+ return ""
+
+
+def _extract_header_from_markdown(mdfile: Iterable[str]) -> str:
+ """For a given markdown file, extract its header line.
+
+ Args:
+ mdfile: iterator to the markdown file.
+
+ Returns:
+ A string for header or empty string if header is not found.
+ """
+ prev_line = ""
+
+ for line in mdfile:
+
+ # Ignore licenses and other non-headers prior to the header.
+ # If we've found the header, return the header.
+ header = _parse_markdown_header(line, prev_line)
+ if header != "":
+ return header
+
+ prev_line = line
+
+ return ""
+
+
+def _remove_license(mdfile_path: str) -> None:
+ """Removes any licenses in markdown files.
+
+ Args:
+ mdfile_path (str): The path to the markdown file.
+ """
+
+ comment_tag_begin = ""
+
+ with open(mdfile_path) as mdfile:
+ file_content = mdfile.read()
+
+ # Find the first occurrence of comment tags.
+ begin_index = file_content.find(comment_tag_begin)
+ end_index = file_content.find(comment_tag_end)
+
+ # Check whether the HTML comment is a license - they should be at the top of
+ # the file, and if any content prior to the license is visible other than
+ # whitespace we assume it's not a license comment.
+ if (pre_comment := file_content[:begin_index]) and not pre_comment.isspace():
+ return
+
+ # Strip the license.
+ file_content = file_content[end_index + len(comment_tag_end):]
+
+ # Reset file position to the beginning to write
+ with open(mdfile_path, 'w') as mdfile:
+ mdfile.write(file_content)
+
+
+def _highlight_md_codeblocks(mdfile_path: str) -> None:
+ """Adds syntax highlighting to code blocks for a given markdown file.
+
+ Args:
+ mdfile_path (str): The path to the markdown file.
+ """
+ fence = '```'
+ fence_with_python = '```python'
+ new_lines = []
+
+ with open(mdfile_path) as mdfile:
+ file_content = mdfile.read()
+ # If there is an odd number of code block annotations, do not syntax
+ # highlight.
+ if file_content.count(fence) % 2 != 0:
+ print(f'{mdfile.name} contains wrong format of code blocks. Skipping syntax highlighting.')
+ return
+ # Retrieve code block positions to replace
+ codeblocks = [[m.start(), m.end()] for m in re.finditer(
+ fence,
+ file_content)]
+
+ # This is equivalent to grabbing every odd index item.
+ codeblocks = codeblocks[::2]
+ # Used to store code blocks that come without language indicators.
+ blocks_without_indicators = []
+
+ # Check if the fence comes without a language indicator. If so, include
+ # this to a list to render.
+ for start, end in codeblocks:
+ if file_content[end] == '\n':
+ blocks_without_indicators.append([start, end])
+
+ # Stitch content that does not need to be parsed, and replace with
+ # `fence_with_python` for parsed portions.
+ prev_start = prev_end = 0
+ for start, end in blocks_without_indicators:
+ new_lines.append(file_content[prev_end:start])
+ new_lines.append(fence_with_python)
+ prev_start, prev_end = start, end
+
+ # Include rest of the content.
+ new_lines.append(file_content[prev_end:])
+
+ # Overwrite with newly parsed content.
+ with open(mdfile_path, 'w') as mdfile:
+ new_content = ''.join(new_lines)
+ mdfile.write(new_content)
+
+
+def _clean_image_links(mdfile_path: str) -> None:
+ """Cleans extra whitespace that breaks image links in index.html file.
+
+ Args:
+ mdfile_path (str): The path to the markdown file.
+ """
+ image_link_pattern=r'\[\s*!\[image\]\(.*\)\s*\]\(.*\)'
+ new_lines = []
+ with open(mdfile_path) as mdfile:
+ file_content = mdfile.read()
+
+ prev_start = prev_end = 0
+
+ for matched_obj in re.finditer(image_link_pattern, file_content):
+ start = matched_obj.start()
+ end = matched_obj.end()
+ matched_str = file_content[start:end]
+ # Clean up all whitespaces for the image link.
+ clean_str = ''.join(matched_str.split())
+
+ new_lines.append(file_content[prev_end:start])
+ new_lines.append(clean_str)
+ prev_start, prev_end = start, end
+
+ new_lines.append(file_content[prev_end:])
+
+ with open(mdfile_path, 'w') as mdfile:
+ new_content = ''.join(new_lines)
+ mdfile.write(new_content)
+
+
+def _prepend_markdown_header(filename: str, mdfile: Iterable[str]) -> None:
+ """Prepends the filename as a Markdown header.
+
+ Args:
+ filename: the name of the markdown file to prepend.
+ mdfile: iterator to the markdown file that is both readable
+ and writable.
+ """
+ file_content = f'# {filename}\n\n' + mdfile.read()
+ # Reset file position to the beginning to write
+ mdfile.seek(0)
+ mdfile.write(file_content)
+
+
+def _merge_markdown_content(
+ *,
+ base_file: str,
+ additional_content_file: str,
+ prepend_additional_content: bool = False,
+) -> None:
+ """Merges the Markdown file contents.
+
+ The additional_content_file's contents get appended to the base_file's
+ content.
+
+ Args:
+ base_file: The base content to append content to.
+ additional_content_file: The additional content to be appended to
+ the base file.
+ prepend_additional_content: Optional. If specified, puts the additional
+ content before the base file content.
+ """
+ try:
+ with (
+ open(base_file, 'r+') as base,
+ open(additional_content_file, 'r') as additional_content
+ ):
+ file_content = (
+ f'{additional_content.read()}\n{base.read()}'
+ if prepend_additional_content
+ else f'{base.read()}\n{additional_content.read()}'
+ )
+ base.seek(0)
+ base.write(file_content)
+ except OSError:
+ print("Could not open the given files.")
+ return
+
+
+def move_markdown_pages(
+ app: sphinx.application,
+ outdir: Path,
+ cwd: list[str] | None = [],
+) -> None:
+ """Moves markdown pages to be added to the generated reference documentation.
+
+ Markdown pages may be hand written or auto generated. They're processed
+ through a third party library to process markdown, then does further
+ processing here then added to the top level of the TOC.
+
+ Args:
+ app: Sphinx application.
+ outdir: The output directory to move markdown pages to.
+ """
+ # Use this to ignore markdown files that are unnecessary.
+ files_to_ignore = [
+ "index.md", # use readme.md instead
+
+ "reference.md", # Reference docs overlap with Overview. Will try and incorporate this in later.
+ # See https://github.com/googleapis/sphinx-docfx-yaml/issues/106.
+ "overview_content.md", # Content will be merged into summary_overview page.
+ ]
+
+ # Use this to move the page but do not add them in the TOC.
+ ignore_in_toc = [
+ "summary_overview.md", # Already included in the TOC with other
+ # summary pages.
+ ]
+
+ files_to_rename = {
+ 'readme.md': 'index.md',
+ }
+
+ base_markdown_dir = Path(app.builder.outdir).parent / "markdown"
+
+ markdown_dir = (
+ base_markdown_dir.joinpath(*cwd)
+ if cwd
+ else base_markdown_dir
+ )
+
+ if not markdown_dir.exists():
+ print("There's no markdown file to move.")
+ return
+
+ # Used to keep track of the index page entry to insert later.
+ index_page_entry = None
+
+ markdown_file_names = {
+ mdfile.name.lower()
+ for mdfile in markdown_dir.iterdir()
+ }
+
+ # If there is an index.md and no readme.md, use the index.md. Otherwise, we ignore the index.md.
+ if ("index.md" in markdown_file_names and
+ "readme.md" not in markdown_file_names):
+ files_to_ignore.remove("index.md")
+
+ if (
+ "summary_overview.md" in markdown_file_names and
+ "overview_content.md" in markdown_file_names
+ ):
+ # Keep the summary_overview file, prepend the additioanl content.
+ _merge_markdown_content(
+ base_file=markdown_dir/"summary_overview.md",
+ additional_content_file=markdown_dir/"overview_content.md",
+ prepend_additional_content=True,
+ )
+
+ # For each file, if it is a markdown file move to the top level pages.
+ for mdfile in markdown_dir.iterdir():
+ if mdfile.is_dir():
+ cwd.append(mdfile.name)
+ move_markdown_pages(app, outdir, cwd)
+ # Restore the original cwd after finish working on the directory.
+ cwd.pop()
+
+ if not mdfile.is_file() or mdfile.name.lower() in files_to_ignore:
+ continue
+
+ mdfile_name = ""
+
+ _remove_license(mdfile)
+
+ # Extract the header name for TOC.
+ with open(mdfile) as mdfile_iterator:
+ name = _extract_header_from_markdown(mdfile_iterator)
+
+ if not name:
+ with open(mdfile, 'r+') as mdfile_iterator:
+ mdfile_name = mdfile_iterator.name.split("/")[-1].split(".")[0].capitalize()
+
+ print(f"Could not find a title for {mdfile_iterator.name}. Using {mdfile_name} as the title instead.")
+ name = mdfile_name
+
+ _prepend_markdown_header(name, mdfile_iterator)
+
+
+ mdfile_name_to_use = mdfile.name.lower()
+ if mdfile_name_to_use in files_to_rename:
+ mdfile_name_to_use = files_to_rename[mdfile_name_to_use]
+
+ if cwd and mdfile_name_to_use == "index.md":
+ mdfile_name_to_use = f"{'_'.join(cwd)}_{mdfile_name_to_use}"
+
+ mdfile_outdir = f"{outdir}/{mdfile_name_to_use}"
+
+ shutil.copy(mdfile, mdfile_outdir)
+
+ _highlight_md_codeblocks(mdfile_outdir)
+ _clean_image_links(mdfile_outdir)
+
+ if mdfile.name.lower() in ignore_in_toc:
+ continue
+
+ app.env.moved_markdown_pages.add(mdfile_name_to_use)
+
+ if not cwd:
+ # Use Overview as the name for top-level index file.
+ if 'index.md' in mdfile_name_to_use:
+ # Save the index page entry.
+ index_page_entry = {
+ 'name': 'Overview',
+ 'href': 'index.md',
+ }
+ continue
+
+ # Use '/' to reserve for top level pages.
+ app.env.markdown_pages['/'].append({
+ 'name': name,
+ 'href': mdfile_name_to_use,
+ })
+ continue
+
+ # Add the file to the TOC later.
+ app.env.markdown_pages[cwd[-1]].append({
+ 'name': name,
+ 'href': mdfile_name_to_use,
+ })
+
+ if app.env.markdown_pages.get('/'):
+ # Sort the top level pages. Other pages will be sorted when they're
+ # added to package level files accordingly.
+ app.env.markdown_pages['/'] = sorted(
+ app.env.markdown_pages['/'],
+ key=lambda entry: entry['href'],
+ )
+
+
+ if index_page_entry is None:
+ return
+
+ # Place the Overview page at the top of the list.
+ app.env.markdown_pages['/'].insert(
+ 0,
+ index_page_entry,
+ )
+
+def remove_unused_pages(
+ added_pages: MutableSet[str],
+ all_pages: MutableSet[str],
+ outdir: Path,
+) -> None:
+ """Removes unused markdown pages after merging the table of contents.
+
+ Pages may be generated as part of generating the document. API pages
+ are needed and may be generated as part of Sphinx config, but if not
+ used they will be identified and removed.
+
+ Args:
+ added_pages: markdown pages that have been added to the merged
+ table of contents.
+ all_pages: set of all markdown pages generated.
+ outdir: output directory containing the markdown pages.
+ """
+
+ pages_to_remove = set(
+ page for page in all_pages
+ if page not in added_pages
+ )
+
+ for page in pages_to_remove:
+ try:
+ os.remove(f"{outdir}/{page}")
+ except FileNotFoundError:
+ # This shouldn't happen, but in case we fail, ignore the failure
+ # and continue deleting other files.
+ print(f"Could not delete {page}.")
+
+
+def run_sphinx_markdown(app: sphinx.application) -> None:
+ """Runs sphinx-build with Markdown builder in the plugin.
+
+ Args:
+ app (sphinx.application): The sphinx application.
+ """
+ cwd = os.getcwd()
+ relative_srcdir = app.srcdir.removeprefix(f"{cwd}/")
+ relative_outdir = app.outdir.removeprefix(f"{cwd}/").removesuffix("/html")
+ # Skip running sphinx-build for Markdown for some unit tests.
+ # Not required other than to output DocFX YAML.
+ if "docs" in cwd:
+ return
+
+ return shell.run(
+ [
+ "sphinx-build",
+ "-M",
+ "markdown",
+ relative_srcdir,
+ relative_outdir,
+ ],
+ hide_output=False
+ )
+
diff --git a/packages/gcp-sphinx-docfx-yaml/docfx_yaml/monkeypatch.py b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/monkeypatch.py
new file mode 100644
index 000000000000..55626102d083
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/monkeypatch.py
@@ -0,0 +1,484 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import re
+from docutils import nodes
+from functools import partial
+
+from sphinx.util.docfields import _is_single_paragraph
+from sphinx.util import docfields
+from sphinx import directives, addnodes
+from sphinx import addnodes
+
+from sphinx.addnodes import desc, desc_signature
+from typing import Any
+from .utils import transform_node as _transform_node
+from .nodes import remarks
+import sphinx.application
+
+TYPE_SEP_PATTERN = r'(\[|\]|, |\(|\))'
+
+def _get_desc_data(node: nodes.Node) -> tuple[str | None, str | None]:
+ """Gets the description data from a node.
+ Args:
+ node (nodes.Node): The node to get the description data from.
+ Returns:
+ tuple[str | None, str | None]: A tuple containing the full name
+ and uid of the node.
+ """
+ assert node.tagname == 'desc'
+ if node.attributes['domain'] != 'py':
+ print(
+ 'Skipping Domain Object (%s)' % node.attributes['domain']
+ )
+ return None, None
+
+ try:
+ module = node[0].attributes['module']
+ full_name = node[0].attributes['fullname'].split('.')[-1]
+ except KeyError as e:
+ print("[docfx_yaml] There maybe some syntax error in docstring near: " + node.astext())
+ raise e
+
+ try:
+ uid = node[0].attributes['ids'][0]
+ except Exception:
+ uid = f'{module}.{full_name}'
+ print('Non-standard id: %s' % uid)
+ return full_name, uid
+
+def _is_desc_of_enum_class(node: nodes.Node) -> bool:
+ """Checks if the node is a description of an enum class.
+ Args:
+ node (nodes.Node): The node to check.
+ Returns:
+ bool: True if the node is a description of an enum class,
+ False otherwise.
+ """
+ assert node.tagname == 'desc_content'
+ if node[0] and node[0].tagname == 'paragraph' and node[0].astext() == 'Bases: enum.Enum':
+ return True
+
+ return False
+
+
+def _hacked_transform(typemap: dict, node: nodes.Node) -> tuple[list, dict]:
+ """
+ Taken from docfields.py from sphinx.
+
+ This does all the steps around gathering data,
+ but doesn't actually do the node transformations.
+ """
+ entries = []
+ groupindices = {}
+ types = {}
+
+ # step 1: traverse all fields and collect field types and content
+ for field in node:
+ fieldname, fieldbody = field
+ try:
+ # split into field type and argument
+ fieldtype, fieldarg = fieldname.astext().split(None, 1)
+ except ValueError:
+ # maybe an argument-less field type?
+ fieldtype, fieldarg = fieldname.astext(), ''
+ typedesc, is_typefield = typemap.get(fieldtype, (None, None))
+
+ # sort out unknown fields
+ if typedesc is None or typedesc.has_arg != bool(fieldarg):
+ # either the field name is unknown, or the argument doesn't
+ # match the spec; capitalize field name and be done with it
+ new_fieldname = fieldtype[0:1].upper() + fieldtype[1:]
+ if fieldarg:
+ new_fieldname += ' ' + fieldarg
+ fieldname[0] = nodes.Text(new_fieldname)
+ entries.append(field)
+ continue
+
+ typename = typedesc.name
+
+ # collect the content, trying not to keep unnecessary paragraphs
+ if _is_single_paragraph(fieldbody):
+ content = fieldbody.children[0].children
+ else:
+ content = fieldbody.children
+
+ # if the field specifies a type, put it in the types collection
+ if is_typefield:
+ # filter out only inline nodes; others will result in invalid
+ # markup being written out
+ content = [n for n in content if isinstance(n, nodes.Inline) or
+ isinstance(n, nodes.Text)]
+ if content:
+ types.setdefault(typename, {})[fieldarg] = content
+ continue
+
+ # also support syntax like ``:param type name:``
+ if typedesc.is_typed:
+ try:
+ argtype, argname = fieldarg.split(None, 1)
+ except ValueError:
+ pass
+ else:
+ types.setdefault(typename, {})[argname] = \
+ [nodes.Text(argtype)]
+ fieldarg = argname
+
+ translatable_content = nodes.inline(fieldbody.rawsource,
+ translatable=True)
+ translatable_content.source = fieldbody.parent.source
+ translatable_content.line = fieldbody.parent.line
+ translatable_content += content
+
+ # grouped entries need to be collected in one entry, while others
+ # get one entry per field
+ if typedesc.is_grouped:
+ if typename in groupindices:
+ group = entries[groupindices[typename]]
+ else:
+ groupindices[typename] = len(entries)
+ group = [typedesc, []]
+ entries.append(group)
+ entry = typedesc.make_entry(fieldarg, [translatable_content])
+ group[1].append(entry)
+ else:
+ entry = typedesc.make_entry(fieldarg, [translatable_content])
+ entries.append([typedesc, entry])
+
+ return (entries, types)
+
+
+def patch_docfields(app: sphinx.application.Sphinx) -> None:
+ """
+ Grab syntax data from the Sphinx info fields.
+
+ This is done by monkeypatching into the DocFieldTransformer,
+ which is what Sphinx uses to transform the docutils ``nodes.field``
+ into the sphinx ``docfields.Field`` objects.
+
+ See usage in Sphinx
+ `here `_.
+
+ This also performs the RST doctree to Markdown transformation on the content,
+ using the :class:`docfx_yaml.writers.MarkdownWriter`.
+ """
+
+ transform_node = partial(_transform_node, app)
+
+ def get_data_structure(entries: list, types: dict, field_object: nodes.Node) -> dict:
+ """
+ Get a proper docfx YAML data structure from the entries & types
+ """
+
+ data = {
+ 'parameters': [],
+ 'variables': [],
+ 'exceptions': [],
+ 'return': {},
+ 'references': [],
+ }
+
+ def make_param(_id, _description, _type=None, _required=None):
+ ret = {
+ 'id': _id,
+ 'description': _description.strip(" \n\r\t")
+ }
+ if _type:
+ ret['type'] = _type
+
+ if _required is not None:
+ ret['isRequired'] = _required
+
+ return ret
+
+ def transform_para(para_field):
+ if isinstance(para_field, addnodes.pending_xref):
+ return transform_node(para_field)
+ else:
+ return para_field.astext()
+
+ def resolve_type(data_type):
+ # Remove @ ~ and \n for cross reference in parameter/return value type to apply to docfx correctly
+ data_type = re.sub('[@~\n]', '', data_type)
+
+ # Add references for docfx to resolve ref if type contains TYPE_SEP_PATTERN
+ _spec_list = []
+ _spec_fullnames = re.split(TYPE_SEP_PATTERN, data_type)
+
+ _added_reference = {}
+ if len(_spec_fullnames) > 1:
+ _added_reference_name = ''
+ for _spec_fullname in _spec_fullnames:
+ if _spec_fullname != '':
+ _spec = {}
+ _spec['name'] = _spec_fullname.split('.')[-1]
+ _spec['fullName'] = _spec_fullname
+ if re.match(TYPE_SEP_PATTERN, _spec_fullname) is None:
+ _spec['uid'] = _spec_fullname
+ _spec_list.append(_spec)
+ _added_reference_name += _spec['name']
+
+ _added_reference = {
+ 'uid': data_type,
+ 'name': _added_reference_name,
+ 'fullName': data_type,
+ 'spec.python': _spec_list
+ }
+
+ return data_type, _added_reference
+
+ def extract_exception_desc(field_object):
+ ret = []
+ if len(field_object) > 0:
+ for field in field_object:
+ if 'field_name' == field[0].tagname and field[0].astext() == 'Raises':
+ assert field[1].tagname == 'field_body'
+ field_body = field[1]
+
+ children = [n for n in field_body
+ if not isinstance(n, nodes.Invisible)]
+
+ for child in children:
+ if isinstance (child, nodes.paragraph):
+ pending_xref_index = child.first_child_matching_class(addnodes.pending_xref)
+ if pending_xref_index is not None:
+ pending_xref = child[pending_xref_index]
+ raise_type_index = pending_xref.first_child_matching_class(nodes.literal)
+ if raise_type_index is not None:
+ raise_type = pending_xref[raise_type_index]
+ ret.append({'type': pending_xref['reftarget'], 'desc': raise_type.astext()})
+
+ return ret
+
+ for entry in entries:
+ if isinstance(entry, nodes.field):
+ # pass-through old field
+ pass
+ else:
+ fieldtype, content = entry
+ fieldtypes = types.get(fieldtype.name, {})
+ if fieldtype.name == 'exceptions':
+ for _type, _description in content:
+ data['exceptions'].append({
+ 'type': _type,
+ 'description': transform_node(_description[0]).strip(" \n\r\t")
+ })
+ if fieldtype.name == 'returntype':
+ for returntype_node in content[1]:
+ returntype_ret = transform_node(returntype_node)
+ if returntype_ret:
+ # Support or in returntype
+ for returntype in re.split('[ \n]or[ \n]', returntype_ret):
+ returntype, _added_reference = resolve_type(returntype)
+ if _added_reference:
+ if len(data['references']) == 0:
+ data['references'].append(_added_reference)
+ elif any(r['uid'] != _added_reference['uid'] for r in data['references']):
+ data['references'].append(_added_reference)
+
+ data['return'].setdefault('type', []).append(returntype)
+ if fieldtype.name == 'returnvalue':
+ returnvalue_ret = transform_node(content[1][0])
+ if returnvalue_ret:
+ data['return']['description'] = returnvalue_ret.strip(" \n\r\t")
+ if fieldtype.name in ['parameter', 'variable', 'keyword']:
+ for field, node_list in content:
+ _id = field
+ _description = transform_node(node_list[0])
+ if field in fieldtypes:
+ _type = u''.join(transform_para(n) for n in fieldtypes[field])
+ else:
+ _type = None
+
+ _para_types = []
+ if fieldtype.name == 'parameter' or fieldtype.name == 'keyword':
+ if _type:
+ # Support or in parameter type
+ for _s_type in re.split('[ \n]or[ \n]', _type):
+ _s_type, _added_reference = resolve_type(_s_type)
+ if _added_reference:
+ if len(data['references']) == 0:
+ data['references'].append(_added_reference)
+ elif any(r['uid'] != _added_reference['uid'] for r in data['references']):
+ data['references'].append(_added_reference)
+
+ _para_types.append(_s_type)
+
+
+
+ _data = make_param(_id=_id, _type=_para_types, _description=_description, _required=False if fieldtype.name == 'keyword' else True)
+ data['parameters'].append(_data)
+
+ if fieldtype.name == 'variable':
+ if _type:
+ # Support or in variable type
+ for _s_type in re.split('[ \n]or[ \n]', _type):
+ _s_type, _added_reference = resolve_type(_s_type)
+ if _added_reference:
+ if len(data['references']) == 0:
+ data['references'].append(_added_reference)
+ elif any(r['uid'] != _added_reference['uid'] for r in data['references']):
+ data['references'].append(_added_reference)
+
+ _para_types.append(_s_type)
+
+ _data = make_param(_id=_id, _type=_para_types, _description=_description)
+ data['variables'].append(_data)
+
+ ret_list = extract_exception_desc(field_object)
+ for ret in ret_list:
+ # only use type in exceptions
+ data.setdefault('exceptions', []).append({
+ 'type': ret['type']
+ })
+
+ return data
+
+
+ class PatchedDocFieldTransformer(docfields.DocFieldTransformer):
+
+ @staticmethod
+ def type_mapping(type_name: str) -> str:
+ """Maps a type name to a docfx type name.
+ Args:
+ type_name (str): The type name to map.
+ Returns:
+ str: The mapped type name.
+ """
+ mapping = {
+ "staticmethod": "method",
+ "classmethod": "method",
+ "exception": "class"
+ }
+
+ return mapping[type_name] if type_name in mapping else type_name
+
+ def __init__(self, directive: Any):
+ """Initializes the transformer.
+ Args:
+ directive (Any): The directive.
+ """
+ self.directive = directive
+ super(PatchedDocFieldTransformer, self).__init__(directive)
+
+ def transform_all(self, node: nodes.Node) -> None:
+ """Transform all field list children of a node."""
+ # don't traverse, only handle field lists that are immediate children
+ summary = []
+ data = {}
+ name, uid = _get_desc_data(node.parent)
+ for child in node:
+ if isinstance(child, remarks):
+ remarks_string = transform_node(child)
+ data['remarks'] = remarks_string
+ elif isinstance(child, addnodes.desc):
+ if child.get('desctype') == 'attribute':
+ attribute_map = {} # Used for detecting duplicated attributes in intermediate data and merge them
+
+ for item in child:
+ if isinstance(item, desc_signature) and any(isinstance(n, addnodes.desc_annotation) for n in item):
+ # capture attributes data and cache it
+ data.setdefault('added_attribute', [])
+
+ item_ids = item.get('ids', [''])
+
+ if len(item_ids) == 0: # find a node with no 'ids' attribute
+ curuid = item.get('module', '') + '.' + item.get('fullname', '')
+ # generate its uid by module and fullname
+ else:
+ curuid = item_ids[0]
+
+ if len(curuid) > 0:
+ parent = curuid[:curuid.rfind('.')]
+ name = item.children[0].astext()
+
+ if curuid in attribute_map:
+ if len(item_ids) == 0: # ensure the order of docstring attributes and real attributes is fixed
+ attribute_map[curuid]['syntax']['content'] += (' ' + item.astext())
+ # concat the description of duplicated nodes
+ else:
+ attribute_map[curuid]['syntax']['content'] = item.astext() + ' ' + attribute_map[curuid]['syntax']['content']
+ else:
+ if _is_desc_of_enum_class(node):
+ addedData = {
+ 'uid': curuid,
+ 'id': name,
+ 'parent': parent,
+ 'langs': ['python'],
+ 'name': name,
+ 'fullName': curuid,
+ 'type': item.parent.get('desctype'),
+ 'module': item.get('module'),
+ 'syntax': {
+ 'content': item.astext(),
+ 'return': {
+ 'type': [parent]
+ }
+ }
+ }
+ else:
+ addedData = {
+ 'uid': curuid,
+ 'class': parent,
+ 'langs': ['python'],
+ 'name': name,
+ 'fullName': curuid,
+ 'type': 'attribute',
+ 'module': item.get('module'),
+ 'syntax': {
+ 'content': item.astext()
+ }
+ }
+
+ attribute_map[curuid] = addedData
+ else:
+ raise Exception('ids of node: ' + repr(item) + ' is missing.')
+ # no ids and no duplicate or uid can not be generated.
+ if 'added_attribute' in data:
+ data['added_attribute'].extend(attribute_map.values()) # Add attributes data to a temp list
+
+ # Don't recurse into child nodes
+ continue
+ elif isinstance(child, nodes.field_list):
+ (entries, types) = _hacked_transform(self.typemap, child)
+ _data = get_data_structure(entries, types, child)
+ data.update(_data)
+ elif isinstance(child, addnodes.seealso):
+ data['seealso'] = transform_node(child)
+ elif isinstance(child, nodes.admonition) and 'Example' in child[0].astext():
+ # Remove the admonition node
+ child_copy = child.deepcopy()
+ child_copy.pop(0)
+ data['example'] = transform_node(child_copy)
+ else:
+ content = transform_node(child)
+
+ # skip 'Bases' in summary
+ if not content.startswith('Bases: '):
+ summary.append(content)
+
+ if "desctype" in node.parent and node.parent["desctype"] == 'class':
+ data.pop('exceptions', '') # Make sure class doesn't have 'exceptions' field.
+
+ if summary:
+ data['summary'] = '\n'.join(summary)
+ # Don't include empty data
+ for key, val in data.copy().items():
+ if not val:
+ del data[key]
+ data['type'] = PatchedDocFieldTransformer.type_mapping(node.parent["desctype"]) if "desctype" in node.parent else 'unknown'
+ self.directive.env.docfx_info_field_data[uid] = data
+ super(PatchedDocFieldTransformer, self).transform_all(node)
+
+ directives.DocFieldTransformer = PatchedDocFieldTransformer
diff --git a/packages/gcp-sphinx-docfx-yaml/docfx_yaml/nodes.py b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/nodes.py
new file mode 100644
index 000000000000..7b54b88bd3d3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/nodes.py
@@ -0,0 +1,34 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# coding: utf-8
+
+"""
+This module is used to add extra supported nodes to sphinx.
+"""
+
+from docutils import nodes
+
+class remarks(nodes.paragraph, nodes.Element):
+ """A docutils node for 'remarks' messages."""
+
+ @staticmethod
+ def visit_remarks(self, node: nodes.Node) -> None:
+ """Visit a 'remarks' node."""
+ self.visit_paragraph(node)
+
+ @staticmethod
+ def depart_remarks(self, node: nodes.Node) -> None:
+ """Depart a 'remarks' node."""
+ self.depart_paragraph(node)
diff --git a/packages/gcp-sphinx-docfx-yaml/docfx_yaml/settings.py b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/settings.py
new file mode 100644
index 000000000000..afa2c46ef8f1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/settings.py
@@ -0,0 +1,24 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Basic settings.
+
+You shouldn't need to touch this.
+"""
+
+import os
+
+
+SITE_ROOT = os.path.dirname(os.path.realpath(__file__))
+API_ROOT = 'docfx_yaml'
diff --git a/packages/gcp-sphinx-docfx-yaml/docfx_yaml/utils.py b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/utils.py
new file mode 100644
index 000000000000..73489dba8f21
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/utils.py
@@ -0,0 +1,83 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import re
+from docutils.io import StringOutput
+from docutils.utils import new_document
+from docutils import nodes
+from inspect import signature
+from collections import namedtuple
+from sphinx.application import Sphinx
+
+
+from .writer import MarkdownWriter as Writer
+
+
+def slugify(value: str) -> str:
+ """Converts to lowercase, removes non-word characters.
+
+ Converts non-word characters (alphanumerics and
+ underscores) and converts spaces to hyphens. Also strips leading and
+ trailing whitespace.
+
+ Args:
+ value (str): The string to convert.
+
+ Returns:
+ str: The converted string.
+ """
+ value = re.sub(r'[^\w\s-]', '', value).strip()
+ return re.sub(r'[-\s]+', '-', value)
+
+
+def transform_string(app: Sphinx, string: str) -> str:
+ """Transforms a string by parsing it and then writing it out.
+
+ This is useful for resolving references in the string.
+
+ Args:
+ app (Sphinx): The sphinx application.
+ string (str): The string to transform.
+
+ Returns:
+ str: The transformed string.
+ """
+ ret = []
+ for para in string.split('\n\n'):
+ tmp = nodes.paragraph(para, para)
+ ret.append(transform_node(app, tmp))
+ return '\n\n'.join(ret)
+
+
+def transform_node(app: Sphinx, node: nodes.Node) -> str:
+ """Transforms a docutils node to a string.
+
+ Args:
+ app (Sphinx): The sphinx application.
+ node (nodes.Node): The node to transform.
+
+ Returns:
+ str: The transformed node as a string.
+ """
+ destination = StringOutput(encoding='utf-8')
+ doc = new_document(b'')
+ doc.append(node)
+
+ # Resolve refs
+ doc['docname'] = 'inmemory'
+ app.env.resolve_references(doctree=doc, fromdocname='inmemory', builder=app.builder)
+
+ writer = Writer(app.builder)
+ writer.write(doc, destination)
+ return destination.destination.decode('utf-8')
diff --git a/packages/gcp-sphinx-docfx-yaml/docfx_yaml/writer.py b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/writer.py
new file mode 100644
index 000000000000..5beb0b4dab61
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docfx_yaml/writer.py
@@ -0,0 +1,1193 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -*- coding: utf-8 -*-
+"""
+This is a forked version of the Sphinx text writer.
+
+It outputs DocFX Markdown from the docutils doctree,
+allowing us to transform transformed RST in memory to markdown.
+
+It is certainly **not** complete,
+and only implement as much logic as would be expected in normal docstring usage.
+It is not intended to be a generic rst->markdown converter,
+because rst contains myriad structures that markdown can't represent.
+"""
+
+import json
+import os
+import re
+import sys
+import textwrap
+from itertools import groupby
+
+
+
+from docutils import nodes, writers
+from docutils.utils import column_width
+from docutils.nodes import TextElement, Text, Node
+
+from sphinx import addnodes
+from sphinx.builders import Builder
+from sphinx.locale import admonitionlabels
+
+from .nodes import remarks
+
+class bcolors:
+ HEADER = '\033[95m'
+ OKBLUE = '\033[94m'
+ OKGREEN = '\033[92m'
+ WARNING = '\033[93m'
+ FAIL = '\033[91m'
+ ENDC = '\033[0m'
+ BOLD = '\033[1m'
+ UNDERLINE = '\033[4m'
+
+
+
+class TextWrapper(textwrap.TextWrapper):
+ """Custom subclass that uses a different word separator regex."""
+
+ wordsep_re = re.compile(
+ r'(\s+|' # any whitespace
+ r'(?<=\s)(?::[a-z-]+:)?`\S+|' # interpreted text start
+ r'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|' # hyphenated words
+ r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))') # em-dash
+
+ def _wrap_chunks(self, chunks: list[str]) -> list[str]:
+ """Wraps chunks of text into lines.
+
+ The original _wrap_chunks uses len() to calculate width.
+ This method respects wide/fullwidth characters for width adjustment.
+
+ Args:
+ chunks (list): A list of strings representing text chunks.
+
+ Returns:
+ list: A list of strings representing the wrapped lines.
+ """
+ drop_whitespace = getattr(self, 'drop_whitespace', True) # py25 compat
+ lines = []
+ if self.width <= 0:
+ raise ValueError("invalid width %r (must be > 0)" % self.width)
+
+ chunks.reverse()
+
+ while chunks:
+ cur_line = []
+ cur_len = 0
+
+ if lines:
+ indent = self.subsequent_indent
+ else:
+ indent = self.initial_indent
+
+ width = self.width - column_width(indent)
+
+ if drop_whitespace and chunks[-1].strip() == '' and lines:
+ del chunks[-1]
+
+ while chunks:
+ l = column_width(chunks[-1])
+
+ if cur_len + l <= width:
+ cur_line.append(chunks.pop())
+ cur_len += l
+
+ else:
+ break
+
+ if chunks and column_width(chunks[-1]) > width:
+ self._handle_long_word(chunks, cur_line, cur_len, width)
+
+ if drop_whitespace and cur_line and cur_line[-1].strip() == '':
+ del cur_line[-1]
+
+ if cur_line:
+ lines.append(indent + ''.join(cur_line))
+
+ return lines
+
+ def _break_word(self, word: str, space_left: int) -> tuple[str, str]:
+ """Breaks a word into two parts.
+
+ Breaks line by unicode width instead of len(word).
+
+ Args:
+ word (str): The word to break.
+ space_left (int): The remaining space on the line.
+
+ Returns:
+ tuple: A tuple containing the two parts of the word.
+ """
+ total = 0
+ for i, c in enumerate(word):
+ total += column_width(c)
+ if total > space_left:
+ return word[:i-1], word[i-1:]
+ return word, ''
+
+ def _split(self, text: str) -> list[str]:
+ """Splits text into chunks.
+
+ Override original method that only split by 'wordsep_re'.
+ This '_split' split wide-characters into chunk by one character.
+
+ Args:
+ text (str): The text to split.
+
+ Returns:
+ list: A list of strings representing the chunks.
+ """
+ def split(t):
+ return textwrap.TextWrapper._split(self, t)
+ chunks = []
+ for chunk in split(text):
+ for w, g in groupby(chunk, column_width):
+ if w == 1:
+ chunks.extend(split(''.join(g)))
+ else:
+ chunks.extend(list(g))
+ return chunks
+
+ def _handle_long_word(
+ self, reversed_chunks: list[str], cur_line: list[str], cur_len: int, width: int
+ ) -> None:
+ """Handles a long word that exceeds the line width.
+
+ Override original method for using self._break_word() instead of slice.
+
+ Args:
+ reversed_chunks (list): A list of reversed text chunks.
+ cur_line (list): The current line being built.
+ cur_len (int): The current length of the line.
+ width (int): The maximum width of the line.
+ """
+ space_left = max(width - cur_len, 1)
+ if self.break_long_words:
+ l, r = self._break_word(reversed_chunks[-1], space_left)
+ cur_line.append(l)
+ reversed_chunks[-1] = r
+
+ elif not cur_line:
+ cur_line.append(reversed_chunks.pop())
+
+
+MAXWIDTH = 999
+STDINDENT = 3
+
+
+def my_wrap(text: str, width: int = MAXWIDTH, **kwargs) -> list[str]:
+ """Wraps the given text to a specified width.
+
+ Args:
+ text (str): The text to wrap.
+ width (int): The maximum width of the lines.
+ **kwargs: Additional keyword arguments for TextWrapper.
+
+ Returns:
+ list[str]: A list of wrapped lines.
+ """
+ w = TextWrapper(width=width, **kwargs)
+ return w.wrap(text)
+
+
+class MarkdownWriter(writers.Writer):
+ """
+ This writer is used to produce the markdown
+ written in yaml files (summaries), it is distinct from the
+ markdown outputter which process the whole documentation.
+ """
+ supported = ('text',)
+ settings_spec = ('No options here.', '', ())
+ settings_defaults = {}
+
+ output = None
+
+ def __init__(self, builder: Builder):
+ """
+ Args:
+ builder (Builder): The sphinx builder.
+ """
+ writers.Writer.__init__(self)
+ self.builder = builder
+ self.translator_class = MarkdownTranslator
+
+ def translate(self) -> None:
+ """Translates the document to markdown."""
+ visitor = self.translator_class(self.document, self.builder)
+ self.document.walkabout(visitor)
+ self.output = visitor.body
+
+
+class MarkdownTranslator(nodes.NodeVisitor):
+ sectionchars = '*=-~"+`'
+ xref_template = ""
+
+ def __init__(self, document: nodes.document, builder: Builder):
+ """
+ Args:
+ document (nodes.document): The document to translate.
+ builder (Builder): The sphinx builder.
+ """
+ self.invdata = []
+ nodes.NodeVisitor.__init__(self, document)
+ self.builder = builder
+
+ newlines = builder.config.text_newlines
+ if newlines == 'windows':
+ self.nl = '\r\n'
+ elif newlines == 'native':
+ self.nl = os.linesep
+ else:
+ self.nl = '\n'
+ self.sectionchars = builder.config.text_sectionchars
+ self.states = [[]]
+ self.stateindent = [0]
+ self.list_counter = []
+ self.sectionlevel = 0
+ self.lineblocklevel = 0
+ self.table = None
+
+ @staticmethod
+ def resolve_reference_in_node(node: Node) -> None:
+ """Resolves references in a node.
+
+ Args:
+ node (Node): The node to resolve references in.
+ """
+ if node.tagname == 'reference':
+ ref_string = MarkdownTranslator._resolve_reference(node)
+
+ if not node.parent is None:
+ for i, n in enumerate(node.parent):
+ if n is node: # Replace the reference node.
+ node.parent.children[i] = Text(ref_string)
+ break
+ else: # If reference node has no parent, replace it's content.
+ node.clear()
+ node.children.append(Text(ref_string))
+ else:
+ for child in node:
+ if isinstance(child, Node):
+ MarkdownTranslator.resolve_reference_in_node(child)
+
+ def add_text(self, text: str) -> None:
+ """Adds text to the current state.
+
+ Args:
+ text (str): The text to add.
+ """
+ self.states[-1].append((-1, text))
+
+ def new_state(self, indent: int = STDINDENT) -> None:
+ """Creates a new state.
+
+ Args:
+ indent (int): The indent for the new state.
+ """
+ self.states.append([])
+ self.stateindent.append(indent)
+
+ def clear_last_state(self) -> tuple[list, int, int]:
+ """Clears the last state."""
+ content = self.states.pop()
+ maxindent = sum(self.stateindent)
+ indent = self.stateindent.pop()
+ return content, maxindent, indent
+
+ def end_state(self, wrap: bool = False, end: list[str] = [''], first: str = None) -> None:
+ """Ends the current state."""
+ content, maxindent, indent = self.clear_last_state()
+ result = []
+ toformat = []
+
+ def do_format():
+ if not toformat:
+ return
+ if wrap:
+ res = my_wrap(''.join(toformat), width=MAXWIDTH-maxindent)
+ else:
+ res = ''.join(toformat).splitlines()
+ if end:
+ res += end
+ result.append((indent, res))
+ for itemindent, item in content:
+ if itemindent == -1:
+ toformat.append(item)
+ else:
+ do_format()
+ result.append((indent + itemindent, item))
+ toformat = []
+ do_format()
+ if first is not None and result:
+ itemindent, item = result[0]
+ result_rest, result = result[1:], []
+ if item:
+ toformat = [first + ' '.join(item)]
+ do_format() # re-create `result` from `toformat`
+ _dummy, new_item = result[0]
+ result.insert(0, (itemindent - indent, [new_item[0]]))
+ result[1] = (itemindent, new_item[1:])
+ result.extend(result_rest)
+ self.states[-1].extend(result)
+
+ def visit_document(self, node: Node) -> None:
+ self.new_state(0)
+
+ def depart_document(self, node: Node) -> None:
+ self.end_state()
+ self.body = self.nl.join(line and (' '*indent + line)
+ for indent, lines in self.states[0]
+ for line in lines)
+ # XXX header/footer?
+
+ def visit_highlightlang(self, node: Node) -> None:
+ raise nodes.SkipNode
+
+ def visit_section(self, node: Node) -> None:
+ self._title_char = self.sectionchars[self.sectionlevel]
+ self.sectionlevel += 1
+
+ def depart_section(self, node: Node) -> None:
+ self.sectionlevel -= 1
+
+ def visit_topic(self, node: Node) -> None:
+ # Skip TOC in the articles
+ raise nodes.SkipNode
+
+ def depart_topic(self, node: Node) -> None:
+ pass
+
+ visit_sidebar = visit_topic
+ depart_sidebar = depart_topic
+
+ def visit_rubric(self, node: Node) -> None:
+ self.new_state(0)
+ self.add_text('-[ ')
+
+ def depart_rubric(self, node: Node) -> None:
+ self.add_text(' ]-')
+ self.end_state()
+
+ def visit_compound(self, node: Node) -> None:
+ pass
+
+ def depart_compound(self, node: Node) -> None:
+ pass
+
+ def visit_glossary(self, node: Node) -> None:
+ pass
+
+ def depart_glossary(self, node: Node) -> None:
+ pass
+
+ def visit_title(self, node: Node) -> None:
+ depth = -1
+ element = node.parent
+ while (element is not None):
+ depth += 1
+ element = element.parent
+ self.add_text(self.nl * 2 + (depth * '#') + ' ')
+
+
+ def depart_title(self, node: Node) -> None:
+ pass
+
+ def visit_subtitle(self, node: Node) -> None:
+ pass
+
+ def depart_subtitle(self, node: Node) -> None:
+ pass
+
+ def visit_attribution(self, node: Node) -> None:
+ self.add_text('-- ')
+
+ def depart_attribution(self, node: Node) -> None:
+ pass
+
+ def visit_desc(self, node: Node) -> None:
+ pass
+
+ def depart_desc(self, node: Node) -> None:
+ pass
+
+ def visit_desc_signature(self, node: Node) -> None:
+ self.new_state(0)
+
+ def depart_desc_signature(self, node: Node) -> None:
+ # XXX: wrap signatures in a way that makes sense
+ self.end_state(wrap=False, end=None)
+
+ def visit_desc_name(self, node: Node) -> None:
+ pass
+
+ def depart_desc_name(self, node: Node) -> None:
+ pass
+
+ def visit_desc_addname(self, node: Node) -> None:
+ pass
+
+ def depart_desc_addname(self, node: Node) -> None:
+ pass
+
+ def visit_desc_type(self, node: Node) -> None:
+ pass
+
+ def depart_desc_type(self, node: Node) -> None:
+ pass
+
+ def visit_desc_returns(self, node: Node) -> None:
+ self.add_text(' -> ')
+
+ def depart_desc_returns(self, node: Node) -> None:
+ pass
+
+ def visit_desc_parameterlist(self, node: Node) -> None:
+ self.add_text('(')
+ self.first_param = 1
+
+ def depart_desc_parameterlist(self, node: Node) -> None:
+ self.add_text(')')
+
+ def visit_desc_parameter(self, node: Node) -> None:
+ if not self.first_param:
+ self.add_text(', ')
+ else:
+ self.first_param = 0
+ self.add_text(node.astext())
+ raise nodes.SkipNode
+
+ def visit_desc_optional(self, node: Node) -> None:
+ self.add_text('[')
+
+ def depart_desc_optional(self, node: Node) -> None:
+ self.add_text(']')
+
+ def visit_desc_annotation(self, node: Node) -> None:
+ pass
+
+ def depart_desc_annotation(self, node: Node) -> None:
+ pass
+
+ def visit_desc_content(self, node: Node) -> None:
+ self.new_state()
+ self.add_text(self.nl)
+
+ def depart_desc_content(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_figure(self, node: Node) -> None:
+ self.new_state()
+
+ def depart_figure(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_caption(self, node: Node) -> None:
+ pass
+
+ def depart_caption(self, node: Node) -> None:
+ pass
+
+ def visit_productionlist(self, node: Node) -> None:
+ self.new_state()
+ names = []
+ for production in node:
+ names.append(production['tokenname'])
+ maxlen = max(len(name) for name in names)
+ lastname = None
+ for production in node:
+ if production['tokenname']:
+ self.add_text(production['tokenname'].ljust(maxlen) + ' ::=')
+ lastname = production['tokenname']
+ elif lastname is not None:
+ self.add_text('%s ' % (' '*len(lastname)))
+ self.add_text(production.astext() + self.nl)
+ self.end_state(wrap=False)
+ raise nodes.SkipNode
+
+ def visit_footnote(self, node: Node) -> None:
+ self._footnote = node.children[0].astext().strip()
+ self.new_state(len(self._footnote) + 3)
+
+ def depart_footnote(self, node: Node) -> None:
+ self.end_state(first='[%s] ' % self._footnote)
+
+ def visit_citation(self, node: Node) -> None:
+ if len(node) and isinstance(node[0], nodes.label):
+ self._citlabel = node[0].astext()
+ else:
+ self._citlabel = ''
+ self.new_state(len(self._citlabel) + 3)
+
+ def depart_citation(self, node: Node) -> None:
+ self.end_state(first='[%s] ' % self._citlabel)
+
+ def visit_label(self, node: Node) -> None:
+ raise nodes.SkipNode
+
+ def visit_legend(self, node: Node) -> None:
+ pass
+
+ def depart_legend(self, node: Node) -> None:
+ pass
+
+ # XXX: option list could use some better styling
+
+ def visit_option_list(self, node: Node) -> None:
+ pass
+
+ def depart_option_list(self, node: Node) -> None:
+ pass
+
+ def visit_option_list_item(self, node: Node) -> None:
+ self.new_state(0)
+
+ def depart_option_list_item(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_option_group(self, node: Node) -> None:
+ self._firstoption = True
+
+ def depart_option_group(self, node: Node) -> None:
+ self.add_text(' ')
+
+ def visit_option(self, node: Node) -> None:
+ if self._firstoption:
+ self._firstoption = False
+ else:
+ self.add_text(', ')
+
+ def depart_option(self, node: Node) -> None:
+ pass
+
+ def visit_option_string(self, node: Node) -> None:
+ pass
+
+ def depart_option_string(self, node: Node) -> None:
+ pass
+
+ def visit_option_argument(self, node: Node) -> None:
+ self.add_text(node['delimiter'])
+
+ def depart_option_argument(self, node: Node) -> None:
+ pass
+
+ def visit_description(self, node: Node) -> None:
+ pass
+
+ def depart_description(self, node: Node) -> None:
+ pass
+
+ def visit_tabular_col_spec(self, node: Node) -> None:
+ raise nodes.SkipNode
+
+ def visit_colspec(self, node: Node) -> None:
+ self.table[0].append(node['colwidth'])
+ raise nodes.SkipNode
+
+ def visit_tgroup(self, node: Node) -> None:
+ pass
+
+ def depart_tgroup(self, node: Node) -> None:
+ pass
+
+ def visit_thead(self, node: Node) -> None:
+ pass
+
+ def depart_thead(self, node: Node) -> None:
+ pass
+
+ def visit_tbody(self, node: Node) -> None:
+ self.table.append('sep')
+
+ def depart_tbody(self, node: Node) -> None:
+ pass
+
+ def visit_row(self, node: Node) -> None:
+ self.table.append([])
+
+ def depart_row(self, node: Node) -> None:
+ pass
+
+ def visit_entry(self, node: Node) -> None:
+ if 'morerows' in node or 'morecols' in node:
+ raise NotImplementedError('Column or row spanning cells are '
+ 'not implemented.')
+ self.new_state(0)
+
+ def depart_entry(self, node: Node) -> None:
+ text = self.nl.join(self.nl.join(x[1]) for x in self.states.pop())
+ self.stateindent.pop()
+ self.table[-1].append(text)
+
+ def visit_table(self, node: Node) -> None:
+ if self.table:
+ raise NotImplementedError('Nested tables are not supported.')
+ self.new_state(0)
+ self.table = [[]]
+ self
+
+ def depart_table(self, node: Node) -> None:
+ lines = self.table[1:]
+ fmted_rows = []
+ colwidths = self.table[0]
+ realwidths = colwidths[:]
+ separator = 0
+ self.add_text(f'')
+ # self.add_text(f'')
+
+ # don't allow paragraphs in table cells for now
+ # for line in lines:
+ # if line == 'sep':
+ # separator = len(fmted_rows)
+ # else:
+ # cells = []
+ # for i, cell in enumerate(line):
+ # par = my_wrap(cell, width=colwidths[i])
+ # if par:
+ # maxwidth = max(column_width(x) for x in par)
+ # else:
+ # maxwidth = 0
+ # realwidths[i] = max(realwidths[i], maxwidth)
+ # cells.append(par)
+ # fmted_rows.append(cells)
+
+ # def writesep(char='-'):
+ # out = ['+']
+ # for width in realwidths:
+ # out.append(char * (width+2))
+ # out.append('+')
+ # self.add_text(''.join(out) + self.nl)
+
+ # def writerow(row):
+ # lines = zip_longest(*row)
+ # for line in lines:
+ # out = ['|']
+ # for i, cell in enumerate(line):
+ # if cell:
+ # adjust_len = len(cell) - column_width(cell)
+ # out.append(' ' + cell.ljust(
+ # realwidths[i] + 1 + adjust_len))
+ # else:
+ # out.append(' ' * (realwidths[i] + 2))
+ # out.append('|')
+ # self.add_text(''.join(out) + self.nl)
+
+ # for i, row in enumerate(fmted_rows):
+ # if separator and i == separator:
+ # writesep('=')
+ # else:
+ # writesep('-')
+ # writerow(row)
+ # writesep('-')
+ self.table = None
+ self.end_state(wrap=False)
+
+ def visit_acks(self, node: Node) -> None:
+ self.new_state(0)
+ self.add_text(', '.join(n.astext() for n in node.children[0].children) +
+ '.')
+ self.end_state()
+ raise nodes.SkipNode
+
+ def visit_image(self, node: Node) -> None:
+ try:
+ image_name = '/'.join(node.attributes['uri'].split('/')[node.attributes['uri'].split('/').index('_static')-1:])
+ except ValueError as e:
+ print(f"Image not found where expected {node.attributes['uri']}")
+ raise nodes.SkipNode
+ image_name = ''.join(image_name.split())
+ self.new_state(0)
+ if 'alt' in node.attributes:
+ self.add_text(f'![{node["alt"]}]({image_name})' + self.nl)
+ self.add_text(f'' + self.nl)
+ self.end_state(False)
+ raise nodes.SkipNode
+
+ def visit_transition(self, node: Node) -> None:
+ indent = sum(self.stateindent)
+ self.new_state(0)
+ self.add_text('=' * (MAXWIDTH - indent))
+ self.end_state()
+ raise nodes.SkipNode
+
+ def visit_bullet_list(self, node: Node) -> None:
+ self.list_counter.append(-1)
+
+ def depart_bullet_list(self, node: Node) -> None:
+ self.list_counter.pop()
+
+ def visit_enumerated_list(self, node: Node) -> None:
+ self.list_counter.append(node.get('start', 1) - 1)
+
+ def depart_enumerated_list(self, node: Node) -> None:
+ self.list_counter.pop()
+
+ def visit_definition_list(self, node: Node) -> None:
+ self.list_counter.append(-2)
+
+ def depart_definition_list(self, node: Node) -> None:
+ self.list_counter.pop()
+
+ def visit_list_item(self, node: Node) -> None:
+ if self.list_counter[-1] == -1:
+ # bullet list
+ self.new_state(2)
+ elif self.list_counter[-1] == -2:
+ # definition list
+ pass
+ else:
+ # enumerated list
+ self.list_counter[-1] += 1
+ self.new_state(len(str(self.list_counter[-1])) + 2)
+
+ def depart_list_item(self, node: Node) -> None:
+ if self.list_counter[-1] == -1:
+ self.end_state(first='* ')
+ elif self.list_counter[-1] == -2:
+ pass
+ else:
+ self.end_state(first='%s. ' % self.list_counter[-1])
+
+ def visit_definition_list_item(self, node: Node) -> None:
+ self._classifier_count_in_li = len(node.traverse(nodes.classifier))
+
+ def depart_definition_list_item(self, node: Node) -> None:
+ pass
+
+ def visit_term(self, node: Node) -> None:
+ self.new_state(0)
+
+ def depart_term(self, node: Node) -> None:
+ if not self._classifier_count_in_li:
+ self.end_state(end=None)
+
+ def visit_termsep(self, node: Node) -> None:
+ self.add_text(', ')
+ raise nodes.SkipNode
+
+ def visit_classifier(self, node: Node) -> None:
+ self.add_text(' : ')
+
+ def depart_classifier(self, node: Node) -> None:
+ self._classifier_count_in_li -= 1
+ if not self._classifier_count_in_li:
+ self.end_state(end=None)
+
+ def visit_definition(self, node: Node) -> None:
+ self.new_state()
+
+ def depart_definition(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_field_list(self, node: Node) -> None:
+ pass
+
+ def depart_field_list(self, node: Node) -> None:
+ pass
+
+ def visit_field(self, node: Node) -> None:
+ pass
+
+ def depart_field(self, node: Node) -> None:
+ pass
+
+ def visit_field_name(self, node: Node) -> None:
+ self.new_state(0)
+
+ def depart_field_name(self, node: Node) -> None:
+ self.add_text(':')
+ self.end_state(end=None)
+
+ def visit_field_body(self, node: Node) -> None:
+ self.new_state()
+
+ def depart_field_body(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_centered(self, node: Node) -> None:
+ pass
+
+ def depart_centered(self, node: Node) -> None:
+ pass
+
+ def visit_hlist(self, node: Node) -> None:
+ pass
+
+ def depart_hlist(self, node: Node) -> None:
+ pass
+
+ def visit_hlistcol(self, node: Node) -> None:
+ pass
+
+ def depart_hlistcol(self, node: Node) -> None:
+ pass
+
+ def visit_admonition(self, node: Node) -> None:
+ self.new_state(0)
+
+ def depart_admonition(self, node: Node) -> None:
+ self.end_state()
+
+ def _visit_admonition(self, node: Node) -> None:
+ self.new_state(2)
+
+ if isinstance(node.children[0], nodes.Sequential):
+ self.add_text(self.nl)
+
+ def _make_depart_admonition(name: str):
+ def depart_admonition(self, node: Node) -> None:
+ self.end_state(first=admonitionlabels[name] + ': ')
+ return depart_admonition
+
+ def _make_depart_alert_box(name: str):
+ def depart_alert_box(self, node: Node) -> None:
+ self.clear_last_state()
+ MarkdownTranslator.resolve_reference_in_node(node)
+ lines = node.astext().split('\n')
+ quoteLines = [f'> {line}\n>' for line in lines]
+ mdStr = '\n> [!{0}]\n{1}'.format(name, '\n'.join(quoteLines))
+ self.add_text(mdStr)
+ return depart_alert_box
+
+ visit_attention = _visit_admonition
+ depart_attention = _make_depart_admonition('attention')
+ visit_caution = _visit_admonition
+ depart_caution = _make_depart_alert_box('CAUTION')
+ visit_danger = _visit_admonition
+ depart_danger = _make_depart_admonition('danger')
+ visit_error = _visit_admonition
+ depart_error = _make_depart_admonition('error')
+ visit_hint = _visit_admonition
+ depart_hint = _make_depart_admonition('hint')
+ visit_important = _visit_admonition
+ depart_important = _make_depart_alert_box('IMPORTANT')
+ visit_note = _visit_admonition
+ depart_note = _make_depart_alert_box('NOTE')
+ visit_tip = _visit_admonition
+ depart_tip = _make_depart_alert_box('TIP')
+ visit_warning = _visit_admonition
+ depart_warning = _make_depart_alert_box('WARNING')
+ visit_seealso = _visit_admonition
+
+ def depart_seealso(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_versionmodified(self, node: Node) -> None:
+ self.new_state(0)
+
+ def depart_versionmodified(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_literal_block(self, node: Node) -> None:
+ try:
+ include_language = None
+ include_lines = None
+ include_highlight = None
+ include_caption = None
+ path = self.builder.confdir
+ relative_path = node.attributes['source'][len(path)+1:]
+
+
+ if 'language' in node.attributes:
+ include_language = node.attributes['language']
+
+ if 'language' in node.attributes:
+ include_language = node.attributes['language']
+
+ if 'caption' in node.attributes:
+ include_caption = node.attributes['caption']
+
+ include_language = (('-' + include_language) if (include_language is not None) else '')
+ include_caption = (('"' + include_caption + '"') if (include_caption is not None) else '')
+
+ self.add_text(f'')
+ except KeyError as e:
+ pass
+ except ValueError as e:
+ pass
+
+ self.new_state(0)
+ self.add_text(f'')
+ self.end_state(wrap=False)
+
+ if 'language' in node.attributes:
+ self.add_text(f'````{node.attributes["language"]}')
+ else:
+ self.add_text('````')
+ self.new_state()
+
+
+ def depart_literal_block(self, node: Node) -> None:
+ self.add_text(self.nl + '````')
+ self.end_state(wrap=False)
+
+ def visit_doctest_block(self, node: Node) -> None:
+ self.add_text(self.nl + '```')
+ self.new_state(0)
+
+ def depart_doctest_block(self, node: Node) -> None:
+ self.add_text(self.nl + '```')
+ self.end_state(wrap=False)
+
+ def visit_line_block(self, node: Node) -> None:
+ self.new_state()
+ self.lineblocklevel += 1
+
+ def depart_line_block(self, node: Node) -> None:
+ self.lineblocklevel -= 1
+ self.end_state(wrap=False, end=None)
+ if not self.lineblocklevel:
+ self.add_text('\n')
+
+ def visit_line(self, node: Node) -> None:
+ pass
+
+ def depart_line(self, node: Node) -> None:
+ self.add_text('\n')
+
+ def visit_block_quote(self, node: Node) -> None:
+ self.new_state()
+
+ def depart_block_quote(self, node: Node) -> None:
+ self.end_state()
+
+ def visit_compact_paragraph(self, node: Node) -> None:
+ pass
+
+ def depart_compact_paragraph(self, node: Node) -> None:
+ pass
+
+ def visit_paragraph(self, node: Node) -> None:
+ if not isinstance(node.parent, nodes.Admonition) or \
+ isinstance(node.parent, addnodes.seealso):
+ self.new_state(0)
+
+ def depart_paragraph(self, node: Node) -> None:
+ if not isinstance(node.parent, nodes.Admonition) or \
+ isinstance(node.parent, addnodes.seealso):
+ self.end_state()
+
+ def visit_target(self, node: Node) -> None:
+ if node.hasattr('refid'):
+ self.new_state(0)
+ self.add_text(f'')
+ raise nodes.SkipNode
+
+ def depart_pending_xref(self, node: Node) -> None:
+ pass
+
+ @classmethod
+ def _resolve_reference(cls, node: Node) -> str:
+ ref_string = None
+ raw_ref_tilde_template = ":class:`~{0}`"
+ raw_ref_template = ":class:`{0}`"
+ if 'refid' in node.attributes:
+ ref_string = f''
+ elif 'refuri' in node.attributes:
+ if 'http' in node.attributes['refuri'] or node.attributes['refuri'][0] == '/':
+ ref_string = f'[{node.astext()}]({node.attributes["refuri"]})'
+ else:
+ # only use id in class and func refuri if its id exists
+ # otherwise, remove '.html#' in refuri
+ # uri_fields[1] is class or function uid. e.g:
+ # case 0 - [module]#[class-uid] (go to if block to use class-uid instead)
+ # case 1 - [module]#module-[module] (go to else block to remove '.html#' in refuri)
+ # case 2 - [class]# (go to else block to remove path and '.html#' in refuri)
+ uri_fields = node.attributes['refuri'].split('#')
+ if len(uri_fields) > 1 and uri_fields[1] and not uri_fields[1].startswith('module'):
+ node.attributes['refuri'] = uri_fields[1]
+ else:
+ fname = os.path.split(node.attributes['refuri'])[-1]
+ pos = fname.find('.html')
+ if pos != -1:
+ node.attributes['refuri'] = fname[0: pos]
+
+ if node.parent.rawsource == raw_ref_tilde_template.format(node.attributes['refuri']) or node.parent.rawsource == raw_ref_template.format(node.attributes['refuri']) or node.parent.tagname == 'document':
+ ref_string = node.attributes['refuri']
+ else:
+ ref_string = cls.xref_template.format(node.attributes['refuri'])
+ else:
+ ref_string = f'{node.tagname}'
+
+ return ref_string
+
+ def visit_reference(self, node: Node) -> None:
+ ref_string = MarkdownTranslator._resolve_reference(node)
+ self.add_text(ref_string)
+ raise nodes.SkipNode
+
+ def depart_reference(self, node: Node) -> None:
+ pass
+
+ def visit_number_reference(self, node: Node) -> None:
+ text = nodes.Text(node.get('title', '#'))
+ self.visit_Text(text)
+ raise nodes.SkipNode
+
+ def visit_download_reference(self, node: Node) -> None:
+ pass
+
+ def depart_download_reference(self, node: Node) -> None:
+ pass
+
+ def visit_emphasis(self, node: Node) -> None:
+ self.add_text('*')
+
+ def depart_emphasis(self, node: Node) -> None:
+ self.add_text('*')
+
+ def visit_literal_emphasis(self, node: Node) -> None:
+ self.add_text('*')
+
+ def depart_literal_emphasis(self, node: Node) -> None:
+ self.add_text('*')
+
+ def visit_strong(self, node: Node) -> None:
+ self.add_text('**')
+
+ def depart_strong(self, node: Node) -> None:
+ self.add_text('**')
+
+ def visit_literal_strong(self, node: Node) -> None:
+ self.add_text('**')
+
+ def depart_literal_strong(self, node: Node) -> None:
+ self.add_text('**')
+
+ def visit_abbreviation(self, node: Node) -> None:
+ self.add_text('')
+
+ def depart_abbreviation(self, node: Node) -> None:
+ if node.hasattr('explanation'):
+ self.add_text(' (%s)' % node['explanation'])
+
+ def visit_title_reference(self, node: Node) -> None:
+ self.add_text('*')
+
+ def depart_title_reference(self, node: Node) -> None:
+ self.add_text('*')
+
+ def visit_literal(self, node: Node) -> None:
+ self.add_text('`')
+
+ def depart_literal(self, node: Node) -> None:
+ self.add_text('`')
+
+ def visit_subscript(self, node: Node) -> None:
+ self.add_text('_')
+
+ def depart_subscript(self, node: Node) -> None:
+ pass
+
+ def visit_superscript(self, node: Node) -> None:
+ self.add_text('^')
+
+ def depart_superscript(self, node: Node) -> None:
+ pass
+
+ def visit_footnote_reference(self, node: Node) -> None:
+ self.add_text('[%s]' % node.astext())
+ raise nodes.SkipNode
+
+ def visit_citation_reference(self, node: Node) -> None:
+ self.add_text('[%s]' % node.astext())
+ raise nodes.SkipNode
+
+ def visit_Text(self, node: Text) -> None:
+ self.add_text(node.astext())
+
+ def depart_Text(self, node: Text) -> None:
+ pass
+
+ def visit_generated(self, node: Node) -> None:
+ pass
+
+ def depart_generated(self, node: Node) -> None:
+ pass
+
+ def visit_inline(self, node: Node) -> None:
+ if 'xref' in node['classes'] or 'term' in node['classes']:
+ self.add_text('*')
+
+ def depart_inline(self, node: Node) -> None:
+ if 'xref' in node['classes'] or 'term' in node['classes']:
+ self.add_text('*')
+
+ def visit_container(self, node: Node) -> None:
+ pass
+
+ def depart_container(self, node: Node) -> None:
+ pass
+
+ def visit_problematic(self, node: Node) -> None:
+ self.add_text('>>')
+
+ def depart_problematic(self, node: Node) -> None:
+ self.add_text('<<')
+
+ def visit_system_message(self, node: Node) -> None:
+ print(bcolors.WARNING + "System message warnings: %s" % node.astext() + bcolors.ENDC)
+ raise nodes.SkipNode
+
+ def visit_comment(self, node: Node) -> None:
+ raise nodes.SkipNode
+
+ def visit_meta(self, node: Node) -> None:
+ # only valid for HTML
+ raise nodes.SkipNode
+
+ def visit_raw(self, node: Node) -> None:
+ if 'text' in node.get('format', '').split():
+ self.new_state(0)
+ self.add_text(node.astext())
+ self.end_state(wrap = False)
+ raise nodes.SkipNode
+
+ def visit_math(self, node: Node) -> None:
+ self.builder.warn('using "math" markup without a Sphinx math extension '
+ 'active, please use one of the math extensions '
+ 'described at http://sphinx-doc.org/ext/math.html',
+ (self.builder.env.docname, node.line))
+ raise nodes.SkipNode
+
+ visit_math_block = visit_math
+
+ def visit_substitution_reference(self, node: Node) -> None:
+ pass
+ def depart_substitution_reference(self, node: Node) -> None:
+ pass
+
+ visit_remarks = remarks.visit_remarks
+
+ depart_remarks = remarks.depart_remarks
+
+ def unknown_visit(self, node: Node) -> None:
+ raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/How_to_Document_Python_API.md b/packages/gcp-sphinx-docfx-yaml/docs/How_to_Document_Python_API.md
new file mode 100644
index 000000000000..370689bfb368
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docs/How_to_Document_Python_API.md
@@ -0,0 +1,354 @@
+How to Document Python API
+===
+
+This is a guidance for writing docstrings of your python code. The API reference will be hosted on [Microsoft Docs][docs].
+***
+
+# Overview
+We generate the API reference documentation from source code files automatically. Actually our tool is an extension for [Sphinx][sphinx]. If you are familiar with [Sphinx][sphinx], section [All Supported Sphinx Directives](#all-supported-sphinx-directives) and [All Supported Inline Markups](#all-supported-inline-markups) will be usefully.
+
+All the docstrings should be written in [reStructuredText][rst] (RST) format.
+
+Find our tool on [Github][docfx_yaml].
+
+## Directives
+Directives are a mechanism to extend the content of RST. Every directive declares a block of content with specific role. Start a new line with `.. directive_name::` to use the directive.
+
+For example, following directive declares a `See Also` content:
+
+``` rst
+An empty line should be added between plain contents and directive blocks as below.
+
+.. seealso:: Content of seealso block.
+ Indents should be used for multiple lines contents.
+
+More plain contens.
+```
+
+### All Supported Sphinx Directives
+
+| directives | description |
+| --------------------: | ------------------------------------------------------------------------------- |
+| *.. seealso::* | Indicating `See Also` content. Read [See Also](#see-also) for more information. |
+| *.. code-block::* | Indicating a code fragment. Read [Code](#code) for more information. |
+| *.. literalinclude::* | Include contents from another file. Read more [here][literalinclude]. |
+| *.. admonition::* | Read [Example](#example) for more information. |
+| *.. title::* | Indicating a title. |
+| *.. remarks::* | Detailed description of class. And other class descriptions should be limited to one or two sentences. See [Remarks](#remarks) |
+
+
+
+## Inline Markups
+
+Inline markups are used to describe detailed information of package members. Such as Modules, Classes, Class Methods, Class Attributes, Functions and Variables. Inline markups follows such fomat:
+
+``` rst
+:inline_markup_name: Description for this markup.
+```
+
+For example, `:param:` describes parameter information of functions:
+
+``` python
+def foo(arg1, arg2):
+ """ Docstring of function foo.
+
+ :param arg1: Describing the first parameter of foo().
+ :param arg2: Describing the second parameter of foo().
+ """
+ pass
+```
+
+### All Supported Inline Markups
+
+| inline markup | description |
+| ------------: | --------------------------------------------------------------------- |
+| *:param:* | Description of a function/method parameter. |
+| *:parameter:* | Alias of :param: |
+| *:arg:* | Alias of :param: |
+| *:argument:* | Alias of :param: |
+| *:key:* | Alias of :param: |
+| *:keyword:* | Alias of :param: |
+| *:type:* | Type of a parameter. Creates a cross-reference if possible. |
+| *:raises:* | That (and when) a specific exception is raised. |
+| *:raise:* | Alias of :raises: |
+| *:except:* | Alias of :raises: |
+| *:exception:* | Alias of :raises: |
+| *:var:* | Description of a variable. Also used for describing class attributes. |
+| *:ivar:* | Alias of :var: |
+| *:cvar:* | Alias of :var: |
+| *:vartype:* | Type of a variable. Creates a cross-reference if possible. |
+| *:returns:* | Description of the return value. |
+| *:return:* | Alias of :returns: |
+| *:rtype:* | Return type. Creates a cross-reference if possible. |
+
+# Details
+
+Following contents will show how to write docstring for specific purposes in detail and give some examples.
+
+## Class
+
+### Attributes
+
+To describe attributes of a class, use `:var:` inline markup. `:vartype:` can be used to tell the type of attributes.
+
+Example:
+``` python
+class Foo(object):
+ """ Docstring of :class:`format.rst.foo.Foo` class in rst format.
+
+ :var attr: Docstring of :class:`format.rst.foo.Foo.attr` from class docstring.
+ :vartype attr: ~format.rst.enum.EnumFoo
+ """
+
+ attr = EnumFoo.VALUE1
+```
+
+### Constructor Parameters
+
+Although docstrings of magic methods and private methods will be ignored. You can still introduce the constructor parameters in class's doc string by using `:param:` and `:type:`
+
+Example:
+``` python
+class Foo(object):
+ """ Docstring of :class:`format.rst.foo.Foo` class in rst format.
+
+ :ivar attr: Docstring of :class:`format.rst.foo.Foo.attr` from class docstring.
+ :vartype attr: ~format.rst.enum.EnumFoo
+
+ :param init_arg1: Parameter init_arg1 from class docstring.
+ :type init_arg1: float
+ :param list[int] init_arg2: Parameter init_arg2 from class docstring.
+ """
+
+ attr = EnumFoo.VALUE1
+```
+
+### Remarks
+
+`.. remarks::` is not a directive supported by Sphinx or RST, but only supported by our tool.
+
+Content of remarks should be as detailed as possible, other contents however, shall be terse enough.
+
+Example:
+``` python
+class DirectivesFoo(object):
+ """ Docstring of class :class:`format.rst.directives.DirectivesFoo`.
+
+ .. remarks:: Remarks from class.
+ Multi-line content should be supported.
+ """
+ pass
+```
+
+## Module
+
+Module's docstring should be the very first line below magic comments. Even before the `import` statements.
+
+For example:
+``` python
+# coding: utf-8
+
+""" Docstring of :mod:`format.rst.foo` module.
+"""
+
+from .enum import EnumFoo
+```
+
+## Package
+
+Packages' docstrings are contained in `__init__.py`. They should obey the same rule as module docstrings.
+
+Example:
+``` python
+# coding: utf-8
+
+""" Package used to test rst-style, google-style and numpy-style docstrings.
+"""
+```
+
+## Methods/Functions
+
+`:param:`, `:type:`, `:raises:`, `:returns:` and `:rtype:` are used to document a function or method.
+
+There are two kinkds of ways to describe function parameters and their type:
+
+``` python
+def class_method(cls, arg1):
+ """ Docstring of :class:`format.rst.foo.Foo.class_method` @classmethod.
+
+ :param cls: Class object of :class:`format.rst.foo.Foo`.
+ :type cls: class
+ :param str arg1: Parameter arg1 of :meth:`format.rst.foo.Foo.class_method`.
+ """
+ pass
+```
+
+Content of `:returns:` shows what is the return value.
+
+`:raises:`, `:type:`, `:rtype:` will create cross references if possible. Contents of `:type:` and `:rtype:` can only be class name or type name. `:raises:` may contain both type name and description. For example:
+
+``` python
+def method_exception(self):
+ """ Docstring of :meth:`format.rst.foo.Foo.method_exception`.
+
+ :raises: :class:`format.rst.foo.FooException` This function raises
+ exception.
+ """
+ raise FooException()
+```
+
+
+## External Links
+
+External links can be written in two formats in RST: inline link and seperate link. Read more [here](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#external-links).
+
+But note that our tool only support inline external link format currently. As an example:
+
+``` python
+def method_external_link(self):
+ """ Docstring of :meth:`format.rst.foo.Foo.method_external_link`.
+ Inline link should be transformed to markdown: `Link Text `_.
+ And seperated link will fail: `Seperated Link`_
+
+ .. _Seperated Link: http://seperated.external.link
+ """
+ pass
+```
+
+## List
+
+Two kinds of RST list formats are fully supported in our tool. Read more about [Bullet Lists](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists) and [Enumerated Lists](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists)
+
+
+
+
+## Include
+
+If you want to include contents from another file, `.. literalinclude::` would be helpful. Further more, you can include certain lines of the files. See more details [here](http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude).
+
+## Example
+
+If you would like to show an example of how to use your API, use `.. amonition::` directive and include "Example" in the content.
+
+Example:
+``` python
+def method_example(self):
+ """ Docstring of :meth:`format.rst.foo.Foo.method_example`.
+
+ .. admonition::
+ This is Example content.
+ Should support multi-line.
+ Can also include file:
+
+ .. literalinclude:: ../format/rst/enum.py
+ """
+ pass
+```
+
+**NOTE**: If you are using Google or Numpy style docstring formating, just using the keyword "Example" will be fine.
+
+## Code
+
+To show a code block, use `.. code-block::` directive. Note that there should be an empty line between the directive and code content, as shown in below:
+
+``` python
+def method_code(self):
+ """ Docstring of :meth:`format.rst.foo.Foo.method_code`.
+
+ .. code-block:: python
+
+ >>> import numpy as np
+ >>> a = np.ndarray([1,2,3,4,5])
+
+ Another way of code block::
+
+ import numpy as np
+ b = np.random.random(10)
+ """
+ pass
+```
+
+
+
+## See Also
+
+`.. seealso::` creates a bolck of content showing readers more information.
+
+Example:
+``` python
+def method_seealso(self):
+ """ Docstring of :meth:`format.rst.foo.Foo.method_seealso`.
+
+ .. seealso::
+ Seealso contents.
+ Multi-line should be supported.
+ And reference to :class:`format.rst.foo.Foo` should be okay.
+ """
+ pass
+```
+
+**NOTE**: `See Also` in Numpy-style docstring must begin with class name or type name.
+
+Example:
+``` python
+def method_seealso(self):
+ """ Docstring of :meth:`fomrmat.numpy.foo.Foo.method_seealso`.
+
+ See Also
+ --------
+ format.numpy.foo.Foo.mathod_note : See also target.
+ """
+ pass
+```
+
+
+## Cross Reference
+
+When you would like to insert a cross reference in your docstring, following markups will be helpful:
+
+1. `:func:`: Referencing a function.
+2. `:meth:`: Referencing a class method.
+3. `:class:`: Referencing a class.
+4. `:mod:`: Referencing a module or a package.
+5. `:any:`: Referencing anything.
+
+All contents of these markups should be the full name of objects. It means you have to use the physical path of a class even if you created a short alias by importing it in `__init__.py`.
+
+Example:
+``` rst
+:func:`package.module.class`
+```
+
+# Google/Numpy Style Docstring
+
+You are free to write your docstrings in these two kinds of styles. Examples are shown [here](http://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html?highlight=numpy).
+
+Although you are able to mix content in these two styles together with RST format contents, it is not recommended by us avoiding potential conflictions.
+
+## Supported Fields
+
+- Args (alias of Parameters)
+- Arguments (alias of Parameters)
+- Example
+- Examples
+- Methods
+- Parameters
+- Return (alias of Returns)
+- Returns
+- Raises
+- References
+- See Also
+
+[docs]: https://docs.microsoft.com
+[sphinx]: http://www.sphinx-doc.org
+[docfx_yaml]: https://github.com/docascode/sphinx-docfx-yaml
+[rst]: http://docutils.sourceforge.net/rst.html
+[literalinclude]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude
+[latex]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/Makefile b/packages/gcp-sphinx-docfx-yaml/docs/Makefile
new file mode 100644
index 000000000000..00ed77ffc735
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docs/Makefile
@@ -0,0 +1,195 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+ @echo "Please use \`make ' where is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " applehelp to make an Apple Help Book"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+ @echo " coverage to run coverage check of the documentation (if enabled)"
+
+clean:
+ rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc"
+
+applehelp:
+ $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+ @echo
+ @echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+ @echo "N.B. You won't be able to view it unless you put it in" \
+ "~/Library/Documentation/Help or install it in your application" \
+ "bundle."
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+ $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+ @echo "Testing of coverage in the sources finished, look at the " \
+ "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+livehtml:
+ sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/Workflow.vsdx b/packages/gcp-sphinx-docfx-yaml/docs/Workflow.vsdx
new file mode 100644
index 000000000000..42e836dfbdae
Binary files /dev/null and b/packages/gcp-sphinx-docfx-yaml/docs/Workflow.vsdx differ
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/api.rst b/packages/gcp-sphinx-docfx-yaml/docs/api.rst
new file mode 100644
index 000000000000..ebcd65e5cf31
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docs/api.rst
@@ -0,0 +1,14 @@
+API
+===
+
+.. automodule:: tests.test_yaml
+ :members:
+ :undoc-members:
+
+.. automodule:: docfx_yaml.extension
+ :members:
+ :undoc-members:
+
+.. automodule:: docfx_yaml.monkeypatch
+ :members:
+ :undoc-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/conf.py b/packages/gcp-sphinx-docfx-yaml/docs/conf.py
new file mode 100644
index 000000000000..9b798dfc5ea5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docs/conf.py
@@ -0,0 +1,312 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -*- coding: utf-8 -*-
+#
+# Sphinx DoxFX YAML documentation build configuration file, created by
+# sphinx-quickstart on Wed Apr 22 15:38:18 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.napoleon',
+ 'docfx_yaml.extension',
+]
+
+import os, sys
+
+sys.path.insert(0, os.path.abspath('..'))
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Sphinx DoxFX YAML'
+copyright = u'2015, Read the Docs, Inc'
+author = u'Read the Docs, Inc'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+
+html_theme = 'alabaster'
+html_sidebars = {
+ '**': [
+ 'about.html',
+ 'navigation.html',
+ 'relations.html',
+ 'searchbox.html',
+ ]
+}
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a `_ signal implemented in autodoc.
+It lives in the ``docfx_yaml/extension.py`` file.
+This signal is triggered at the processing of the docstring,
+passing it along unprocessed.
+This allows us to properly get the content of the docstring,
+as well as derive the unique ID (uid) of the object.
+
+Another important part of the ``autodoc-process-docstring`` signal is that it passes the actual Python object along with it.
+This allows us to introspect it with the ``inspect`` Python module,
+and pull off argument listings,
+default values,
+line numbers,
+and other information about the actual object.
+This was required because we wanted more information about the objects than Sphinx outputs in it's normal output around autodoc.
+
+.. warning::
+ This will only work for autodoc generated strings.
+ Any other use of the Python domain will be ignored,
+ as it isn't using the ``autodoc`` module.
+
+YAML syntax
+-----------
+
+The ``docfx`` tool does not have support for Python concepts.
+As such,
+we have done a lossy mapping of the Python concepts onto the equivalent C# concepts.
+This is lossy becuase there are things that can be expressed in Python that can't be in C#,
+for example functions that live outside of a class.
+
+The `YAML Syntax`_ is documented and should be output properly from this module.
+The mapping is done as follows:
+
+.. literalinclude:: ../docfx_yaml/extension.py
+ :start-after: TYPE_MAPPING = {
+ :end-before: }
+
+Along with this mapping,
+all module-level functions will be added to a proxy class called ``Global``.
+This will allow them to be attached to a proper class,
+and be defined with ``docfx``.
+
+.. _domain: http://www.sphinx-doc.org/en/1.5.1/domains.html
+.. _YAML Syntax: https://dotnet.github.io/docfx/spec/metadata_dotnet_spec.html
+
+Sphinx Implementation
+~~~~~~~~~~~~~~~~~~~~~
+
+The user will run a normal ``make html`` as part of their build.
+The generation and loading will be done as an extension that can be configured.
+
+They will then be output into ``docfx_yaml`` inside the documentation directory.
+
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/docfx.json b/packages/gcp-sphinx-docfx-yaml/docs/docfx.json
new file mode 100644
index 000000000000..9cc171b94764
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docs/docfx.json
@@ -0,0 +1,22 @@
+{
+ "build": {
+ "content": [
+ {
+ "files": [ "**/*.yml" ],
+ "cwd": "_build",
+ "dest": "api"
+ },
+ ],
+ "resource": [
+ {
+ "files": [ "articles/images/**"]
+ }
+ ],
+ "overwrite": "specs/*.md",
+ "globalMetadata": {
+ "_appTitle": "docfx seed website",
+ "_enableSearch": true
+ },
+ "dest": "_site"
+ }
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/index.rst b/packages/gcp-sphinx-docfx-yaml/docs/index.rst
new file mode 100644
index 000000000000..72a33558153f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docs/index.rst
@@ -0,0 +1 @@
+.. include:: ../README.rst
diff --git a/packages/gcp-sphinx-docfx-yaml/docs/layout.rst b/packages/gcp-sphinx-docfx-yaml/docs/layout.rst
new file mode 100644
index 000000000000..c5d6dc07e10e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/docs/layout.rst
@@ -0,0 +1,19 @@
+Layout of the project
+=====================
+
+This project has a couple components:
+
+* This repo, which houses the YAML conversion code:
+ * https://github.com/ericholscher/sphinx-docfx-yaml/
+* There is a Travis CI build that tests the actual Python YAML generation code on Python 2 & 3:
+ * https://github.com/ericholscher/sphinx-docfx-yaml/blob/master/.travis.yml
+* The Appveyor CI build that works as an integration test for the Python SDK library:
+ * https://github.com/ericholscher/sphinx-docfx-yaml/blob/master/appveyor.yml
+* The HTML output of the CI build, which does a full life cycle Sphinx->YAML->Docfx conversion:
+ * https://ci.appveyor.com/project/ericholscher/sphinx-docfx-yaml/build/artifacts
+ * The YAML is in the ``doc/_build/html/docfx_yaml`` directory
+ * The rendered HTML is in the ``doc/_site/api/html/docfx_yaml`` directory
+ * The generated YAML is also checked into GitHub here: https://github.com/bradygaster/python-sdk-dev/tree/eric-full-yaml-test/python-sdk-dev/docfx_yaml
+* A forked version of the Python SDK that adds integrates the YAML output and the docfx configuration:
+ * https://github.com/Azure/azure-sdk-for-python/compare/master...ericholscher:add-docfx-yaml
+ * This is used in the CI steps above to make sure we properly generate the YAML & docfx docs
diff --git a/packages/gcp-sphinx-docfx-yaml/renovate.json b/packages/gcp-sphinx-docfx-yaml/renovate.json
new file mode 100644
index 000000000000..e75a31a5cce2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/renovate.json
@@ -0,0 +1,11 @@
+{
+ "extends": [
+ "config:base",
+ ":preserveSemverRanges",
+ ":disableDependencyDashboard"
+ ],
+ "ignorePaths": [".pre-commit-config.yaml", ".kokoro/requirements.txt", "setup.py"],
+ "pip_requirements": {
+ "fileMatch": ["requirements-test.txt", "samples/[\\S/]*constraints.txt", "samples/[\\S/]*constraints-test.txt"]
+ }
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/requirements.txt b/packages/gcp-sphinx-docfx-yaml/requirements.txt
new file mode 100644
index 000000000000..4643a93fd8ce
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/requirements.txt
@@ -0,0 +1,11 @@
+# Install Sphinx plugin
+-e .
+
+# Tox specific dependencies
+tox
+mock
+pytest
+
+# Other dependencies
+black==25.9.0
+parameterized==0.8.1
diff --git a/packages/gcp-sphinx-docfx-yaml/scripts/decrypt-secrets.sh b/packages/gcp-sphinx-docfx-yaml/scripts/decrypt-secrets.sh
new file mode 100755
index 000000000000..120b0ddc4364
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/scripts/decrypt-secrets.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# Copyright 2024 Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+ROOT=$( dirname "$DIR" )
+
+# Work from the project root.
+cd $ROOT
+
+# Prevent it from overriding files.
+# We recommend that sample authors use their own service account files and cloud project.
+# In that case, they are supposed to prepare these files by themselves.
+if [[ -f "testing/test-env.sh" ]] || \
+ [[ -f "testing/service-account.json" ]] || \
+ [[ -f "testing/client-secrets.json" ]]; then
+ echo "One or more target files exist, aborting."
+ exit 1
+fi
+
+# Use SECRET_MANAGER_PROJECT if set, fallback to cloud-devrel-kokoro-resources.
+PROJECT_ID="${SECRET_MANAGER_PROJECT:-cloud-devrel-kokoro-resources}"
+
+gcloud secrets versions access latest --secret="python-docs-samples-test-env" \
+ --project="${PROJECT_ID}" \
+ > testing/test-env.sh
+gcloud secrets versions access latest \
+ --secret="python-docs-samples-service-account" \
+ --project="${PROJECT_ID}" \
+ > testing/service-account.json
+gcloud secrets versions access latest \
+ --secret="python-docs-samples-client-secrets" \
+ --project="${PROJECT_ID}" \
+ > testing/client-secrets.json
diff --git a/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/readme_gen.py b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/readme_gen.py
new file mode 100644
index 000000000000..8f5e248a0da1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/readme_gen.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Generates READMEs using configuration defined in yaml."""
+
+import argparse
+import io
+import os
+import subprocess
+
+import jinja2
+import yaml
+
+
+jinja_env = jinja2.Environment(
+ trim_blocks=True,
+ loader=jinja2.FileSystemLoader(
+ os.path.abspath(os.path.join(os.path.dirname(__file__), "templates"))
+ ),
+ autoescape=True,
+)
+
+README_TMPL = jinja_env.get_template("README.tmpl.rst")
+
+
+def get_help(file):
+ return subprocess.check_output(["python", file, "--help"]).decode()
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument("source")
+ parser.add_argument("--destination", default="README.rst")
+
+ args = parser.parse_args()
+
+ source = os.path.abspath(args.source)
+ root = os.path.dirname(source)
+ destination = os.path.join(root, args.destination)
+
+ jinja_env.globals["get_help"] = get_help
+
+ with io.open(source, "r") as f:
+ config = yaml.load(f)
+
+ # This allows get_help to execute in the right directory.
+ os.chdir(root)
+
+ output = README_TMPL.render(config)
+
+ with io.open(destination, "w") as f:
+ f.write(output)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/README.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/README.tmpl.rst
new file mode 100644
index 000000000000..4fd239765b0a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/README.tmpl.rst
@@ -0,0 +1,87 @@
+{# The following line is a lie. BUT! Once jinja2 is done with it, it will
+ become truth! #}
+.. This file is automatically generated. Do not edit this file directly.
+
+{{product.name}} Python Samples
+===============================================================================
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+ :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/README.rst
+
+
+This directory contains samples for {{product.name}}. {{product.description}}
+
+{{description}}
+
+.. _{{product.name}}: {{product.url}}
+
+{% if required_api_url %}
+To run the sample, you need to enable the API at: {{required_api_url}}
+{% endif %}
+
+{% if required_role %}
+To run the sample, you need to have `{{required_role}}` role.
+{% endif %}
+
+{{other_required_steps}}
+
+{% if setup %}
+Setup
+-------------------------------------------------------------------------------
+
+{% for section in setup %}
+
+{% include section + '.tmpl.rst' %}
+
+{% endfor %}
+{% endif %}
+
+{% if samples %}
+Samples
+-------------------------------------------------------------------------------
+
+{% for sample in samples %}
+{{sample.name}}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+{% if not sample.hide_cloudshell_button %}
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+ :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/{{sample.file}},{{folder}}/README.rst
+{% endif %}
+
+
+{{sample.description}}
+
+To run this sample:
+
+.. code-block:: bash
+
+ $ python {{sample.file}}
+{% if sample.show_help %}
+
+ {{get_help(sample.file)|indent}}
+{% endif %}
+
+
+{% endfor %}
+{% endif %}
+
+{% if cloud_client_library %}
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source`_ and `report issues`_.
+
+.. _Google Cloud Client Library for Python:
+ https://googlecloudplatform.github.io/google-cloud-python/
+.. _browse the source:
+ https://github.com/GoogleCloudPlatform/google-cloud-python
+.. _report issues:
+ https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+{% endif %}
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/auth.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/auth.tmpl.rst
new file mode 100644
index 000000000000..1446b94a5e3a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/auth.tmpl.rst
@@ -0,0 +1,9 @@
+Authentication
+++++++++++++++
+
+This sample requires you to have authentication setup. Refer to the
+`Authentication Getting Started Guide`_ for instructions on setting up
+credentials for applications.
+
+.. _Authentication Getting Started Guide:
+ https://cloud.google.com/docs/authentication/getting-started
diff --git a/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/auth_api_key.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/auth_api_key.tmpl.rst
new file mode 100644
index 000000000000..11957ce2714a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/auth_api_key.tmpl.rst
@@ -0,0 +1,14 @@
+Authentication
+++++++++++++++
+
+Authentication for this service is done via an `API Key`_. To obtain an API
+Key:
+
+1. Open the `Cloud Platform Console`_
+2. Make sure that billing is enabled for your project.
+3. From the **Credentials** page, create a new **API Key** or use an existing
+ one for your project.
+
+.. _API Key:
+ https://developers.google.com/api-client-library/python/guide/aaa_apikeys
+.. _Cloud Console: https://console.cloud.google.com/project?_
diff --git a/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/install_deps.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/install_deps.tmpl.rst
new file mode 100644
index 000000000000..6f069c6c87a5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/install_deps.tmpl.rst
@@ -0,0 +1,29 @@
+Install Dependencies
+++++++++++++++++++++
+
+#. Clone python-docs-samples and change directory to the sample directory you want to use.
+
+ .. code-block:: bash
+
+ $ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions.
+
+ .. _Python Development Environment Setup Guide:
+ https://cloud.google.com/python/setup
+
+#. Create a virtualenv. Samples are compatible with Python 3.7+.
+
+ .. code-block:: bash
+
+ $ virtualenv env
+ $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+ .. code-block:: bash
+
+ $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
diff --git a/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/install_portaudio.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/install_portaudio.tmpl.rst
new file mode 100644
index 000000000000..5ea33d18c00c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/scripts/readme-gen/templates/install_portaudio.tmpl.rst
@@ -0,0 +1,35 @@
+Install PortAudio
++++++++++++++++++
+
+Install `PortAudio`_. This is required by the `PyAudio`_ library to stream
+audio from your computer's microphone. PyAudio depends on PortAudio for cross-platform compatibility, and is installed differently depending on the
+platform.
+
+* For Mac OS X, you can use `Homebrew`_::
+
+ brew install portaudio
+
+ **Note**: if you encounter an error when running `pip install` that indicates
+ it can't find `portaudio.h`, try running `pip install` with the following
+ flags::
+
+ pip install --global-option='build_ext' \
+ --global-option='-I/usr/local/include' \
+ --global-option='-L/usr/local/lib' \
+ pyaudio
+
+* For Debian / Ubuntu Linux::
+
+ apt-get install portaudio19-dev python-all-dev
+
+* Windows may work without having to install PortAudio explicitly (it will get
+ installed with PyAudio).
+
+For more details, see the `PyAudio installation`_ page.
+
+
+.. _PyAudio: https://people.csail.mit.edu/hubert/pyaudio/
+.. _PortAudio: http://www.portaudio.com/
+.. _PyAudio installation:
+ https://people.csail.mit.edu/hubert/pyaudio/#downloads
+.. _Homebrew: http://brew.sh
diff --git a/packages/gcp-sphinx-docfx-yaml/setup.py b/packages/gcp-sphinx-docfx-yaml/setup.py
new file mode 100644
index 000000000000..4fa5b37bf3ec
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/setup.py
@@ -0,0 +1,60 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import codecs
+import setuptools
+
+name = 'gcp-sphinx-docfx-yaml'
+description = 'Sphinx Python Domain to DocFX YAML Generator'
+version = '3.2.4'
+dependencies = [
+ 'black',
+ 'gcp-docuploader',
+ 'PyYAML',
+ 'recommonmark',
+ 'sphinxcontrib-applehelp==1.0.4',
+ 'sphinxcontrib-devhelp==1.0.2',
+ 'sphinxcontrib-htmlhelp==2.0.1',
+ 'sphinxcontrib-qthelp==1.0.3',
+ 'sphinxcontrib-serializinghtml==1.1.5',
+ 'sphinx==4.5.0',
+ 'sphinx-markdown-builder==0.5.5',
+ 'sphinxcontrib.napoleon',
+ 'unidecode',
+ 'wheel>=0.24.0'
+]
+
+packages = setuptools.find_packages('.', exclude=['tests'])
+
+extra_setup = dict(
+setup_requires=['pytest-runner'],
+tests_require=['pytest', 'mock'],
+)
+
+setuptools.setup(
+ name=name,
+ version=version,
+ description=description,
+ author='Google LLC',
+ author_email='dandhlee@google.com',
+ license='Apache 2.0',
+ url='https://github.com/googleapis/sphinx-docfx-yaml',
+ package_dir={'': '.'},
+ packages=packages,
+ install_requires=dependencies,
+ python_requires=">=3.10",
+ include_package_data=True,
+ zip_safe=False,
+ **extra_setup
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/testing/.gitignore b/packages/gcp-sphinx-docfx-yaml/testing/.gitignore
new file mode 100644
index 000000000000..b05fbd630881
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/testing/.gitignore
@@ -0,0 +1,3 @@
+test-env.sh
+service-account.json
+client-secrets.json
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/testing/test_goldens.py b/packages/gcp-sphinx-docfx-yaml/testing/test_goldens.py
new file mode 100644
index 000000000000..21ae3172a9d0
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/testing/test_goldens.py
@@ -0,0 +1,141 @@
+'''Temporarily disabled, moved over to unblock the repository.
+'''
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pathlib import Path
+import difflib
+import filecmp
+import os
+import shutil
+import sys
+
+from docuploader import shell
+
+import pytest
+
+from sphinx.application import Sphinx
+
+
+@pytest.mark.parametrize(
+ "test_dir", ["handwritten", "gapic-combo", "gapic-auto", "non-cloud", "auth"]
+)
+def test_goldens(update_goldens, test_dir):
+ source_dir = Path("tests/testdata") / test_dir
+ golden_dir = Path("tests/testdata/goldens") / test_dir
+
+ docs_dir = source_dir / "docs"
+ build_dir = docs_dir / "_build"
+
+ if build_dir.exists():
+ shutil.rmtree(build_dir)
+
+ out_dir = build_dir / "html/docfx_yaml"
+
+ # Install dependencies.
+ try:
+ shell.run(
+ [
+ sys.executable,
+ "-m",
+ "pip",
+ "install",
+ "-e",
+ ".[all]",
+ "recommonmark",
+ ],
+ cwd=source_dir,
+ hide_output=False,
+ )
+ except Exception as e:
+ pytest.fail(f"build raised an exception: {e}")
+
+ # Generate!
+ try:
+ shell.run(
+ [
+ "sphinx-build",
+ # Settings to be used for sphinx-build
+ "-D",
+ # Extensions to be added
+ (
+ "extensions=sphinx.ext.autodoc,"
+ "sphinx.ext.autosummary,"
+ "docfx_yaml.extension,"
+ "sphinx.ext.intersphinx,"
+ "sphinx.ext.coverage,"
+ "sphinx.ext.napoleon,"
+ "sphinx.ext.todo,"
+ "sphinx.ext.viewcode,"
+ "recommonmark"
+ ),
+ # builder to use
+ "-b",
+ "html",
+ # cache directory path
+ "-d",
+ "docs/_build/doctrees/",
+ # source directory
+ "docs/",
+ # output directory for HTML
+ "docs/_build/html",
+ ],
+ cwd=source_dir,
+ hide_output=False,
+ )
+ except Exception as e:
+ pytest.fail(f"build raised an exception: {e}")
+
+ if update_goldens:
+ shutil.rmtree(golden_dir, ignore_errors=True)
+ shutil.copytree(out_dir, golden_dir, dirs_exist_ok=True)
+ pytest.skip(
+ "Updated goldens! Re-run the test without the --update-goldens flag."
+ )
+
+ got_files = [os.path.relpath(f, out_dir) for f in out_dir.rglob("*")]
+ golden_files = [os.path.relpath(f, golden_dir) for f in golden_dir.rglob("*")]
+
+ nl = "\n"
+ extra = "Extra:\n" + "\n+ ".join([f for f in got_files if f not in golden_files])
+ missing = "Missing:\n" + "\n- ".join(
+ [f for f in golden_files if f not in got_files]
+ )
+
+ assert len(got_files) == len(
+ golden_files
+ ), f"got {len(got_files)} files, want {len(golden_files)}:{nl}{extra}{nl}{missing}"
+
+ (eq, neq, other) = filecmp.cmpfiles(out_dir, golden_dir, got_files, shallow=False)
+ other = [(out_dir / f).as_posix() for f in other]
+
+ if other:
+ pytest.fail(f"found unknown files (should never happen): {other}")
+ if neq:
+ diff = ""
+ for f in neq:
+ with open(out_dir / f) as out:
+ with open(golden_dir / f) as gold:
+ out_lines = out.readlines()
+ gold_lines = gold.readlines()
+ diff = "\n" + "\n".join(
+ difflib.context_diff(
+ gold_lines,
+ out_lines,
+ fromfile=str(golden_dir / f),
+ tofile=str(out_dir / f),
+ )
+ )
+
+ pytest.fail(f"got files that don't match goldens: {diff}")
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/conftest.py b/packages/gcp-sphinx-docfx-yaml/tests/conftest.py
new file mode 100644
index 000000000000..1f0c4a964e03
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/conftest.py
@@ -0,0 +1,37 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+
+
+def pytest_addoption(parser):
+ """Adds a command line option to pytest.
+
+ Args:
+ parser: The pytest parser.
+ """
+ parser.addoption("--update-goldens", action="store", default=False)
+
+
+@pytest.fixture
+def update_goldens(request):
+ """Returns the value of the --update-goldens command line option.
+
+ Args:
+ request: The pytest request object.
+
+ Returns:
+ The value of the --update-goldens command line option.
+ """
+ return request.config.getoption("--update-goldens")
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/cross_references_post.yaml b/packages/gcp-sphinx-docfx-yaml/tests/cross_references_post.yaml
new file mode 100644
index 000000000000..c61a7256a62d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/cross_references_post.yaml
@@ -0,0 +1,52 @@
+## YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "SQL text filtering statement, similar to a WHERE clause in a\n \
+ \ query. Aggregates are not supported.\n \n Examples: \"int_field > 5\"\
+ \ \"date_field = CAST('2014-9-27' as\n DATE)\" \"nullable_field is not NULL\"\
+ \ \"st_equals(geo_field,\n st_geofromtext(\"POINT(2, 2)\"))\" \"numeric_field\
+ \ BETWEEN 1.0\n AND 5.0\"\n \n Restricted to a maximum length for 1 MB."
+ id: google.cloud.bigquery_storage_v1.types.StreamStats
+ var_type: str
+ - description: "Optional. Options specific to the Apache\n Arrow output format."
+ id: arrow_serialization_options
+ var_type: google.cloud.bigquery_storage_v1.types.ArrowSerializationOptions
+ children: []
+ class: google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions
+ fullName: google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions
+ inheritance:
+ - inheritance:
+ - type: builtins.object
+ type: proto.message.Message
+ langs:
+ - python
+ module: google.cloud.bigquery_storage_v1.types.ReadSession
+ name: TableReadOptions
+ source:
+ id: TableReadOptions
+ path: google/cloud/bigquery_storage_v1/types/stream.py
+ remote:
+ branch: main
+ path: google/cloud/bigquery_storage_v1/types/stream.py
+ repo: git@github.com:googleapis/python-bigquery-storage.git
+ startLine: 85
+ summary: "Options dictating how we read a table.\n\
+ \nNames of the fields in the table that should be read in google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions."
+ syntax:
+ content: TableReadOptions(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ exceptions:
+ - description: If the request failed for any reason.
+ var_type: google.api_core.exceptions.GoogleAPICallError
+ parameters:
+ - description: Required. Name of the stream to start reading from, of the form
+ projects/{project_id}/locations/{location}/sessions/{session_id}/streams/{stream_id}
+ with google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse
+ id: row
+ var_type: google.cloud.bigquery_storage_v1.types.AvroRows
+ returns:
+ - description: An iterable of ReadRowsResponse .
+ var_type: ReadRowsStream
+ type: class
+ uid: google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/cross_references_pre.yaml b/packages/gcp-sphinx-docfx-yaml/tests/cross_references_pre.yaml
new file mode 100644
index 000000000000..d7d65b800f41
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/cross_references_pre.yaml
@@ -0,0 +1,52 @@
+## YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "SQL text filtering statement, similar to a WHERE clause in a\n \
+ \ query. Aggregates are not supported.\n \n Examples: \"int_field > 5\"\
+ \ \"date_field = CAST('2014-9-27' as\n DATE)\" \"nullable_field is not NULL\"\
+ \ \"st_equals(geo_field,\n st_geofromtext(\"POINT(2, 2)\"))\" \"numeric_field\
+ \ BETWEEN 1.0\n AND 5.0\"\n \n Restricted to a maximum length for 1 MB."
+ id: google.cloud.bigquery_storage_v1.types.StreamStats
+ var_type: str
+ - description: "Optional. Options specific to the Apache\n Arrow output format."
+ id: arrow_serialization_options
+ var_type: google.cloud.bigquery_storage_v1.types.ArrowSerializationOptions
+ children: []
+ class: google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions
+ fullName: google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions
+ inheritance:
+ - inheritance:
+ - type: builtins.object
+ type: proto.message.Message
+ langs:
+ - python
+ module: google.cloud.bigquery_storage_v1.types.ReadSession
+ name: TableReadOptions
+ source:
+ id: TableReadOptions
+ path: google/cloud/bigquery_storage_v1/types/stream.py
+ remote:
+ branch: main
+ path: google/cloud/bigquery_storage_v1/types/stream.py
+ repo: git@github.com:googleapis/python-bigquery-storage.git
+ startLine: 85
+ summary: "Options dictating how we read a table.\n\
+ \nNames of the fields in the table that should be read in google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions."
+ syntax:
+ content: TableReadOptions(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ exceptions:
+ - description: If the request failed for any reason.
+ var_type: google.api_core.exceptions.GoogleAPICallError
+ parameters:
+ - description: Required. Name of the stream to start reading from, of the form
+ `projects/{project_id}/locations/{location}/sessions/{session_id}/streams/{stream_id}`
+ with google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse
+ id: row
+ var_type: google.cloud.bigquery_storage_v1.types.AvroRows
+ returns:
+ - description: An iterable of ReadRowsResponse .
+ var_type: ReadRowsStream
+ type: class
+ uid: google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example.md
new file mode 100644
index 000000000000..a2208b1d295f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example.md
@@ -0,0 +1,4 @@
+# Test header for a simple markdown file.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_additional_content.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_additional_content.md
new file mode 100644
index 000000000000..c9f4701e3785
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_additional_content.md
@@ -0,0 +1,3 @@
+## This is the additional content.
+
+Additional content to be appended.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate.md
new file mode 100644
index 000000000000..9945014edf88
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate.md
@@ -0,0 +1,7 @@
+This is a simple alternate header
+=================================
+
+With a different style
+----------------------
+
+This is a simple markdown file testing for different header style.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_bad.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_bad.md
new file mode 100644
index 000000000000..e500ba9a8718
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_bad.md
@@ -0,0 +1,6 @@
+==============
+
+There should be a header line before the divider.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_bad_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_bad_want.md
new file mode 100644
index 000000000000..c282c5580e82
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_bad_want.md
@@ -0,0 +1,8 @@
+# Markdown_example_alternate_bad
+
+==============
+
+There should be a header line before the divider.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_header.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_header.md
new file mode 100644
index 000000000000..ec83c70305be
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_header.md
@@ -0,0 +1,20 @@
+
+
+This is a simple alternate header
+=================================
+
+With a different style
+----------------------
+
+This is a simple markdown file testing for different header style.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_less.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_less.md
new file mode 100644
index 000000000000..38194ce908d6
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_alternate_less.md
@@ -0,0 +1,7 @@
+This is a simple alternate header
+=========
+
+With less divider length but it's still a header.
+--------
+
+This is a markdown file to test for alternate header style with shorter divider.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_header.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_header.md
new file mode 100644
index 000000000000..6a3a1893ba25
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_header.md
@@ -0,0 +1,4 @@
+ #Test header for a bad formatted markdown file.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_header_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_header_want.md
new file mode 100644
index 000000000000..01cc5f5c74f7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_header_want.md
@@ -0,0 +1,6 @@
+# Markdown_example_bad_header
+
+ #Test header for a bad formatted markdown file.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_image_links.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_image_links.md
new file mode 100644
index 000000000000..d09059c85195
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_image_links.md
@@ -0,0 +1,23 @@
+# Python Client for Google Cloud Storage API
+
+[
+
+
+
+](https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels) [
+
+
+
+](https://pypi.org/project/google-cloud-storage/) [
+
+
+
+](https://pypi.org/project/google-cloud-storage/)
+
+[Google Cloud Storage API](https://cloud.google.com/storage): is a durable and highly available object storage service. Google Cloud Storage is almost infinitely scalable and guarantees consistency: when a write succeeds, the latest copy of the object will be returned to any GET, globally.
+
+
+* [Client Library Documentation](https://cloud.google.com/python/docs/reference/storage/latest)
+
+
+* [Product Documentation](https://cloud.google.com/storage)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_image_links_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_image_links_want.md
new file mode 100644
index 000000000000..fa01fb2989aa
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_bad_image_links_want.md
@@ -0,0 +1,11 @@
+# Python Client for Google Cloud Storage API
+
+[](https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels) [](https://pypi.org/project/google-cloud-storage/) [](https://pypi.org/project/google-cloud-storage/)
+
+[Google Cloud Storage API](https://cloud.google.com/storage): is a durable and highly available object storage service. Google Cloud Storage is almost infinitely scalable and guarantees consistency: when a write succeeds, the latest copy of the object will be returned to any GET, globally.
+
+
+* [Client Library Documentation](https://cloud.google.com/python/docs/reference/storage/latest)
+
+
+* [Product Documentation](https://cloud.google.com/storage)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_base.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_base.md
new file mode 100644
index 000000000000..d9c5a65c3224
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_base.md
@@ -0,0 +1,3 @@
+# Base markdown file content.
+
+This is the content for base Markdown file.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_base_expected.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_base_expected.md
new file mode 100644
index 000000000000..86a1d3befcf2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_base_expected.md
@@ -0,0 +1,7 @@
+# Base markdown file content.
+
+This is the content for base Markdown file.
+
+## This is the additional content.
+
+Additional content to be appended.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_h2.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_h2.md
new file mode 100644
index 000000000000..bc90dbe2c64d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_h2.md
@@ -0,0 +1,4 @@
+## Test header for a simple markdown file.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_h2_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_h2_want.md
new file mode 100644
index 000000000000..d952cdc68637
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_h2_want.md
@@ -0,0 +1,6 @@
+# Markdown_example_h2
+
+## Test header for a simple markdown file.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header.md
new file mode 100644
index 000000000000..58d221014824
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header.md
@@ -0,0 +1,15 @@
+ # Test header for a simple markdown file.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_want.md
new file mode 100644
index 000000000000..a085794d70ac
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_want.md
@@ -0,0 +1,4 @@
+ # Test header for a simple markdown file.
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_with_comments.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_with_comments.md
new file mode 100644
index 000000000000..cf93126e63a3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_with_comments.md
@@ -0,0 +1,10 @@
+# Test header for a simple markdown file.
+
+
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_with_comments_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_with_comments_want.md
new file mode 100644
index 000000000000..cf93126e63a3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_header_with_comments_want.md
@@ -0,0 +1,10 @@
+# Test header for a simple markdown file.
+
+
+
+##Content header
+This is a simple line followed by an h2 header.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_noheader.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_noheader.md
new file mode 100644
index 000000000000..6a69ee4571a0
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_noheader.md
@@ -0,0 +1,5 @@
+This is a simple markdown file with no header.
+
+When running the test on this file to extract its header,
+
+it should use the filename as the title.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_prepended_base.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_prepended_base.md
new file mode 100644
index 000000000000..fca450a94b8e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_example_prepended_base.md
@@ -0,0 +1,7 @@
+## This is the additional content.
+
+Additional content to be appended.
+
+# Base markdown file content.
+
+This is the content for base Markdown file.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_mixed_highlight.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_mixed_highlight.md
new file mode 100644
index 000000000000..1b9c6cd77306
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_mixed_highlight.md
@@ -0,0 +1,15 @@
+```python
+These code blocks should not be highlighted.
+```
+
+```py
+As these come with a language indicator.
+```
+
+```java
+Shouldn't matter which langauge indicator is used.
+```
+
+```
+But this block should get highlighted.
+```
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_mixed_highlight_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_mixed_highlight_want.md
new file mode 100644
index 000000000000..6e19859e1404
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_mixed_highlight_want.md
@@ -0,0 +1,15 @@
+```python
+These code blocks should not be highlighted.
+```
+
+```py
+As these come with a language indicator.
+```
+
+```java
+Shouldn't matter which langauge indicator is used.
+```
+
+```python
+But this block should get highlighted.
+```
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_no_highlight.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_no_highlight.md
new file mode 100644
index 000000000000..fc4a03fe3792
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_no_highlight.md
@@ -0,0 +1,7 @@
+```
+File with missing codeblock
+```
+
+```
+with no closing bracket
+
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_no_highlight_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_no_highlight_want.md
new file mode 100644
index 000000000000..fc4a03fe3792
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_no_highlight_want.md
@@ -0,0 +1,7 @@
+```
+File with missing codeblock
+```
+
+```
+with no closing bracket
+
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_syntax_highlight.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_syntax_highlight.md
new file mode 100644
index 000000000000..d3daf654c4d7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_syntax_highlight.md
@@ -0,0 +1,9 @@
+```
+test markdown file for
+highlighing markdown codeblocks
+```
+
+```
+all code blocks
+should be highlighted
+```
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/markdown_syntax_highlight_want.md b/packages/gcp-sphinx-docfx-yaml/tests/markdown_syntax_highlight_want.md
new file mode 100644
index 000000000000..5fa792e4c469
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/markdown_syntax_highlight_want.md
@@ -0,0 +1,9 @@
+```python
+test markdown file for
+highlighing markdown codeblocks
+```
+
+```python
+all code blocks
+should be highlighted
+```
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/test_helpers.py b/packages/gcp-sphinx-docfx-yaml/tests/test_helpers.py
new file mode 100644
index 000000000000..7bb7ec579335
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/test_helpers.py
@@ -0,0 +1,406 @@
+from docfx_yaml import extension
+
+import unittest
+from parameterized import parameterized
+
+from yaml import load, Loader
+
+import tempfile
+
+class TestGenerate(unittest.TestCase):
+ """Tests for the extension."""
+ code_testdata = [
+ # Check that the code indents to left based on first line.
+ [
+ \
+""" def foo():
+ print('test function for indent')
+ return ('left-indented-code')
+""",
+ \
+"""def foo():
+ print('test function for indent')
+ return ('left-indented-code')
+"""
+ ],
+ # Check that if there's no whitespace, it does not indent
+ [
+ \
+"""
+print('test function for no impact indent')
+for i in range(10):
+ print(i)
+ if i%5 == 0:
+ i += 1
+ else:
+ continue
+""",
+ \
+"""
+print('test function for no impact indent')
+for i in range(10):
+ print(i)
+ if i%5 == 0:
+ i += 1
+ else:
+ continue
+"""
+ ],
+ ]
+ @parameterized.expand(code_testdata)
+ def test_indent_code_left(self, code, code_want):
+ parts = code.split("\n")
+ tab_space = len(parts[0]) - len(parts[0].lstrip(" "))
+ code_got = extension.indent_code_left(code, tab_space)
+ self.assertEqual(code_got, code_want)
+
+
+ def test_indent_code_blocks_left(self):
+ # Check code blocks are indented properly.
+ code_want = \
+"""def foo():
+
+ print('test function for indent')
+
+ return ('left-indented-blocks')
+"""
+
+ # Test with how blocks would appear in the code block
+ code = [
+ " def foo():",
+ " print('test function for indent')",
+ " return ('left-indented-blocks')\n"
+ ]
+ tab_space = len(code[0]) - len(code[0].lstrip(" "))
+ code_got = "\n\n".join([extension.indent_code_left(part, tab_space) for part in code])
+ self.assertEqual(code_got, code_want)
+
+
+ def test_extract_keyword(self):
+ # Check that keyword properly gets processed.
+ keyword_want = "attribute"
+
+ keyword_line = ".. attribute:: "
+ keyword_got = extension.extract_keyword(keyword_line)
+
+ self.assertEqual(keyword_got, keyword_want)
+
+ # Check that keyword is not retrieved for bad formats.
+ keyword_line = ".. attribute:"
+
+ # Should raise an exception..
+ with self.assertRaises(ValueError):
+ keyword_got = extension.extract_keyword(keyword_line)
+
+
+ cross_references_testdata = [
+ # Testing for normal input.
+ [
+ "google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse",
+ "google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse "
+ ],
+ # Testing for no cross references to convert.
+ [
+ "Response message for SplitReadStreamResponse.",
+ "Response message for SplitReadStreamResponse."
+ ],
+ # Testing for cross references to convert within longer content.
+ [
+ "Response message for google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse.",
+ "Response message for google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse ."
+ ],
+ # Testing for cross reference to not be converted for its own object.
+ [
+ "Response message for google.cloud.bigquery_storage_v1.types.SplitResponse.",
+ "Response message for google.cloud.bigquery_storage_v1.types.SplitResponse."
+ ],
+ # TODO(https://github.com/googleapis/sphinx-docfx-yaml/issues/208):
+ # remove this when it is not needed anymore.
+ # Testing for hardcoded reference.
+ [
+ "google.iam.v1.iam_policy_pb2.GetIamPolicyRequest",
+ "google.iam.v1.iam_policy_pb2.GetIamPolicyRequest "
+ ],
+ ]
+ @parameterized.expand(cross_references_testdata)
+ def test_convert_cross_references(self, content, content_want):
+ # Check that entries correctly turns into cross references.
+ keyword_map = [
+ "google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse",
+ "google.cloud.bigquery_storage_v1.types.SplitResponse"
+ ]
+ current_object_name = "google.cloud.bigquery_storage_v1.types.SplitResponse"
+
+ content_got = extension.convert_cross_references(content, current_object_name, keyword_map)
+ self.assertEqual(content_got, content_want)
+
+ cross_references_test_data = [
+ [
+ """
+ Examples:
+ google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse: test content.
+ """,
+ """
+ Examples:
+ google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse: test content.
+ """,
+ ],
+ ]
+ @parameterized.expand(cross_references_testdata)
+ def test_does_not_convert_for_examples(self, content, content_want):
+ # Check that entries correctly turns into cross references.
+ keyword_map = [
+ "google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse",
+ "google.cloud.bigquery_storage_v1.types.SplitResponse"
+ ]
+ current_object_name = "google.cloud.bigquery_storage_v1.types.SplitResponse"
+
+ content_got = extension.convert_cross_references(content, current_object_name, keyword_map, ignore_examples=True)
+ self.assertEqual(content_got, content_want)
+
+ # Test data used to test for processing already-processed cross references.
+ cross_references_short_testdata = [
+ [
+ "Response message for google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse.",
+ "Response message for google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse ."
+ ],
+ ]
+ @parameterized.expand(cross_references_short_testdata)
+ def test_convert_cross_references_twice(self, content, content_want):
+ keyword_map = [
+ "google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse"
+ ]
+ current_name = "SplitRepsonse"
+
+ content_got = extension.convert_cross_references(content, current_name, keyword_map)
+
+ # Make sure that same entries are not processed twice.
+ # The output should not be different.
+ current = content_got
+ current_got = extension.convert_cross_references(current, content, keyword_map)
+ self.assertEqual(content_want, current_got)
+
+ # If shorter version of the current name exists, it should not interfere
+ # unless strictly necessary.
+ keyword_map.append("google.cloud.bigquery_storage_v1.types")
+ long_name_got = extension.convert_cross_references(content, current_name, keyword_map)
+ self.assertEqual(long_name_got, content_want)
+
+ shorter_name_want = "google.cloud.bigquery_storage_v1.types "
+ shorter_name = "google.cloud.bigquery_storage_v1.types"
+ shorter_name_got = extension.convert_cross_references(shorter_name, current_name, keyword_map)
+ self.assertEqual(shorter_name_got, shorter_name_want)
+
+
+ def test_search_cross_references(self):
+ # Test for a given YAML file.
+ keyword_map = [
+ "google.cloud.bigquery_storage_v1.types.ThrottleState",
+ "google.cloud.bigquery_storage_v1.types.StreamStats.Progress",
+ "google.cloud.bigquery_storage_v1.types.StreamStats",
+ "google.cloud.bigquery_storage_v1.types.SplitReadStreamResponse",
+ "google.cloud.bigquery_storage_v1.types.SplitReadStreamRequest",
+ "google.cloud.bigquery_storage_v1.types.ReadStream",
+ "google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions",
+ "google.cloud.bigquery_storage_v1.types.ReadSession.TableModifiers",
+ "google.cloud.bigquery_storage_v1.types.ReadSession",
+ "google.cloud.bigquery_storage_v1.types.ReadRowsResponse",
+ "google.cloud.bigquery_storage_v1.types.ReadRowsRequest",
+ "google.cloud.bigquery_storage_v1.types.DataFormat",
+ "google.cloud.bigquery_storage_v1.types.CreateReadSessionRequest",
+ "google.cloud.bigquery_storage_v1.types.AvroSchema",
+ "google.cloud.bigquery_storage_v1.types.AvroRows",
+ "google.cloud.bigquery_storage_v1.types.ArrowSerializationOptions.CompressionCodec",
+ "google.cloud.bigquery_storage_v1.types.ArrowSerializationOptions",
+ "google.cloud.bigquery_storage_v1.types.ArrowSchema",
+ "google.cloud.bigquery_storage_v1.types.ArrowRecordBatch",
+ "google.cloud.bigquery_storage_v1.types",
+ ]
+ current_name = "google.cloud.bigquery_storage_v1.types.ReadSession.TableReadOptions"
+ with open('tests/cross_references_pre.yaml', 'r') as test_file:
+ yaml_pre = load(test_file, Loader=Loader)
+
+ for obj in yaml_pre['items']:
+ extension.search_cross_references(obj, current_name, keyword_map)
+
+ with open('tests/cross_references_post.yaml', 'r') as want_file:
+ yaml_post = load(want_file, Loader=Loader)
+
+ self.assertEqual(yaml_pre, yaml_post)
+
+ test_code_params = [
+ [
+ # Test formatting regular Python code.
+ "batch_predict(*, gcs_source: Optional[Union[str, Sequence[str]]] = None, instances_format: str = \"jsonl\", gcs_destination_prefix: Optional[str] = None, predictions_format: str = \"jsonl\", model_parameters: Optional[Dict] = None, machine_type: Optional[str] = None, accelerator_type: Optional[str] = None, explanation_parameters: Optional[google.cloud.aiplatform_v1.types.explanation.ExplanationParameters] = None, labels: Optional[Dict[str, str]] = None, sync: bool = True,)",
+ "batch_predict(\n *,\n gcs_source: Optional[Union[str, Sequence[str]]] = None,\n instances_format: str = \"jsonl\",\n gcs_destination_prefix: Optional[str] = None,\n predictions_format: str = \"jsonl\",\n model_parameters: Optional[Dict] = None,\n machine_type: Optional[str] = None,\n accelerator_type: Optional[str] = None,\n explanation_parameters: Optional[\n google.cloud.aiplatform_v1.types.explanation.ExplanationParameters\n ] = None,\n labels: Optional[Dict[str, str]] = None,\n sync: bool = True,\n)",
+ ],
+ [
+ # Test formatting code with content.
+ "TableAsync(client: google.cloud.bigtable.data._async.client.BigtableDataClientAsync, instance_id: str, table_id: str, app_profile_id: typing.Optional[str] = None, *, default_read_rows_operation_timeout: float = 600, default_read_rows_attempt_timeout: float | None = 20, default_mutate_rows_operation_timeout: float = 600, default_mutate_rows_attempt_timeout: float | None = 60, default_operation_timeout: float = 60, default_attempt_timeout: float | None = 20, default_read_rows_retryable_errors: typing.Sequence[type[Exception]] = (, , ), default_mutate_rows_retryable_errors: typing.Sequence[type[Exception]] = (, ), default_retryable_errors: typing.Sequence[type[Exception]] = (, ))",
+ "TableAsync(\n client: google.cloud.bigtable.data._async.client.BigtableDataClientAsync,\n instance_id: str,\n table_id: str,\n app_profile_id: typing.Optional[str] = None,\n *,\n default_read_rows_operation_timeout: float = 600,\n default_read_rows_attempt_timeout: float | None = 20,\n default_mutate_rows_operation_timeout: float = 600,\n default_mutate_rows_attempt_timeout: float | None = 60,\n default_operation_timeout: float = 60,\n default_attempt_timeout: float | None = 20,\n default_read_rows_retryable_errors: typing.Sequence[type[Exception]] = (\n google.api_core.exceptions.DeadlineExceeded,\n google.api_core.exceptions.ServiceUnavailable,\n google.api_core.exceptions.Aborted,\n ),\n default_mutate_rows_retryable_errors: typing.Sequence[type[Exception]] = (\n google.api_core.exceptions.DeadlineExceeded,\n google.api_core.exceptions.ServiceUnavailable,\n ),\n default_retryable_errors: typing.Sequence[type[Exception]] = (\n google.api_core.exceptions.DeadlineExceeded,\n google.api_core.exceptions.ServiceUnavailable,\n )\n)",
+ ],
+ [
+ # Test formatting code with <... object> content.
+ "read_rows(start_key=None, end_key=None, limit=None, filter_=None, end_inclusive=False, row_set=None, retry=)",
+ "read_rows(\n start_key=None,\n end_key=None,\n limit=None,\n filter_=None,\n end_inclusive=False,\n row_set=None,\n retry=google.api_core.retry.retry_unary.Retry,\n)",
+ ],
+ ]
+ @parameterized.expand(test_code_params)
+ def test_format_code(self, code, code_want):
+ # Test to ensure black formats strings properly.
+ code_got = extension.format_code(code)
+ self.assertEqual(code_want, code_got)
+
+
+ def test_extract_product_name(self):
+ # Test to ensure different name formats extract product name properly.
+ name_want = "scheduler_v1.types.Digest"
+ name = "google.cloud.scheduler_v1.types.Digest"
+ product_name = extension.extract_product_name(name)
+
+ self.assertEqual(name_want, product_name)
+
+ non_cloud_name = "google.scheduler_v1.types.Digest"
+ non_cloud_product_name = extension.extract_product_name(non_cloud_name)
+
+ self.assertEqual(name_want, non_cloud_product_name)
+
+ short_name_want = "Digest"
+ short_name = "scheduler_v1.types.Digest"
+ short_product_name = extension.extract_product_name(short_name)
+
+ self.assertEqual(short_name_want, short_product_name)
+
+
+ test_reference_params = [
+ [
+ # If no reference keyword is found, check for None
+ "google.cloud.resourcemanager_v3.ProjectsClient",
+ ["google.cloud.resourcemanager_v1.ProjectsClient"],
+ ["The", "following", "constraints", "apply", "when", "using"],
+ None
+ ],
+ [
+ # If keyword reference is found, validate proper cross reference
+ "google.cloud.resourcemanager_v3.set_iam_policy",
+ ["google.cloud.resourcemanager_v3.set_iam_policy"],
+ ["A", "Policy", "is", "a", "collection", "of", "bindings", "from"],
+ "google.cloud.resourcemanager_v3.set_iam_policy"
+ ],
+ [
+ # If keyword reference has already been converted, do not convert
+ # again.
+ "uid=\"google.cloud.resourcemanager_v3.set_iam_policy\">documentation",
+ ["google.cloud.resourcemanager_v3.set_iam_policy"],
+ ["Take", "a", "look", "at", "documentation for more information.
+"""
+ # Break up the paragraph into sanitized list of words as shown in Sphinx.
+ words = " ".join(content.split("\n")).split(" ")
+
+ index = words.index(current_word)
+
+ cross_reference_got = extension.find_uid_to_convert(
+ current_word, words, index, uids, current_object_name, visited_words
+ )
+ self.assertEqual(cross_reference_got, cross_reference_want)
+
+ test_summary = [
+ [
+ """Retrieve the ``ID`` for the object.
+
+See https://cloud.google.com/storage/docs/json_api/v1/objects
+
+The ID consists of the bucket name, object name, and generation number.
+ """,
+ """Retrieve the `ID` for the object.
+
+See https://cloud.google.com/storage/docs/json_api/v1/objects
+
+The ID consists of the bucket name, object name, and generation number.
+ """,
+ ],
+ [
+ # Test that codeblocks don't get formatted.
+ """The ID of the blob or `None`.
+
+if the blob's resource has not been loaded from the server.
+
+For example:
+```
+ ID or None
+```
+ """,
+ """The ID of the blob or `None`.
+
+if the blob's resource has not been loaded from the server.
+
+For example:
+```
+ ID or None
+```
+ """,
+ ],
+ ]
+ @parameterized.expand(test_summary)
+ def test_reformat_summary(self, summary, summary_want):
+ summary_got = extension.reformat_summary(summary)
+ self.assertEqual(summary_want, summary_got)
+
+
+ syntax_testdata = [
+ [
+ 'None',
+ ],
+ [
+ \
+"""
+google.cloud.pubsub_v1.message.Message
+""",
+ ],
+ [
+ 'Callable[[], int]',
+ ],
+ ]
+ @parameterized.expand(syntax_testdata)
+ def test_is_valid_python_code(self, syntax):
+ result = extension.is_valid_python_code(syntax)
+ self.assertTrue(result)
+
+
+ invalid_syntax_testdata = [
+ [
+ 'This should not be considered valid Python code.',
+ ],
+ [
+ # Typo in code
+ 'Callable[]',
+ ],
+ ]
+ @parameterized.expand(invalid_syntax_testdata)
+ def test_is_not_valid_python_code(self, invalid_syntax):
+ result = extension.is_valid_python_code(invalid_syntax)
+ self.assertFalse(result)
+
+
+if __name__ == '__main__':
+ unittest.main()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/test_inspect.py b/packages/gcp-sphinx-docfx-yaml/tests/test_inspect.py
new file mode 100644
index 000000000000..8061989fe61b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/test_inspect.py
@@ -0,0 +1,56 @@
+"""Tests for various inspect related utils."""
+from docfx_yaml import extension
+
+import inspect
+import unittest
+from parameterized import parameterized
+
+from typing import Any, Optional, Union
+
+
+class TestGenerate(unittest.TestCase):
+
+ types_to_test = [
+ [
+ # Test for a simple type without __args__.
+ str,
+ 'str',
+ ],
+ [
+ # Test for a more complex type without forward reference.
+ list[str],
+ 'list[str]',
+ ],
+ [
+ # Test for imported type, without forward reference.
+ dict[str, Any],
+ 'dict[str, typing.Any]',
+ ],
+ [
+ # Test for forward reference.
+ Optional["ForwardClass"],
+ 'typing.Optional[ForwardClass]',
+ ],
+ [
+ # Test for multiple forward references.
+ Union["ForwardClass", "ForwardClass2"],
+ 'typing.Union[ForwardClass, ForwardClass2]'
+ ],
+ ]
+ @parameterized.expand(types_to_test)
+ def test_extracts_annotations(self, type_to_test, expected_type_name):
+ """Extracts annotations from test method, compares to expected name."""
+ def test_method(name: type_to_test):
+ pass
+
+ annotations = inspect.getfullargspec(test_method).annotations
+ annotation_to_use = annotations['name']
+
+ extracted_annotation_name = extension._extract_type_name(
+ annotation_to_use)
+
+ self.assertEqual(extracted_annotation_name, expected_type_name)
+
+
+if __name__ == '__main__':
+ unittest.main()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/test_markdown.py b/packages/gcp-sphinx-docfx-yaml/tests/test_markdown.py
new file mode 100644
index 000000000000..8060882b9f77
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/test_markdown.py
@@ -0,0 +1,354 @@
+from docfx_yaml import markdown_utils
+
+import unittest
+from unittest.mock import patch
+from parameterized import parameterized
+import pathlib
+
+import os
+from yaml import load, Loader
+
+import pytest
+import tempfile
+
+class TestGenerate(unittest.TestCase):
+ # Filenames to test markdown syntax highlight with.
+ test_markdown_filenames = [
+ [
+ "tests/markdown_syntax_highlight.md",
+ "tests/markdown_syntax_highlight_want.md"
+ ],
+ [
+ "tests/markdown_no_highlight.md",
+ "tests/markdown_no_highlight_want.md"
+ ],
+ [
+ "tests/markdown_mixed_highlight.md",
+ "tests/markdown_mixed_highlight_want.md"
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_highlight_md_codeblocks(self, base_filename, want_filename):
+ # Test to ensure codeblocks in markdown files are correctly highlighted.
+
+ # Copy the base file we'll need to test.
+ with tempfile.NamedTemporaryFile(mode='r+', delete=False) as test_file:
+ with open(base_filename) as base_file:
+ test_file.write(base_file.read())
+ test_file.flush()
+
+ markdown_utils._highlight_md_codeblocks(test_file.name)
+ test_file.seek(0)
+
+ with open(want_filename) as mdfile_want:
+ self.assertEqual(test_file.read(), mdfile_want.read())
+
+
+ # Filenames to test prepending Markdown title..
+ test_markdown_filenames = [
+ [
+ "tests/markdown_example_bad_header.md",
+ "tests/markdown_example_bad_header_want.md"
+ ],
+ [
+ "tests/markdown_example_h2.md",
+ "tests/markdown_example_h2_want.md"
+ ],
+ [
+ "tests/markdown_example_alternate_bad.md",
+ "tests/markdown_example_alternate_bad_want.md"
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_prepend_markdown_header(self, base_filename, want_filename):
+ # Ensure markdown titles are correctly prepended.
+
+ # Copy the base file we'll need to test.
+ with tempfile.NamedTemporaryFile(mode='r+', delete=False) as test_file:
+ with open(base_filename) as base_file:
+ # Use same file name extraction as original code.
+ file_name = base_file.name.split("/")[-1].split(".")[0].capitalize()
+ test_file.write(base_file.read())
+ test_file.flush()
+ test_file.seek(0)
+
+ markdown_utils._prepend_markdown_header(file_name, test_file)
+ test_file.seek(0)
+
+ with open(want_filename) as mdfile_want:
+ self.assertEqual(test_file.read(), mdfile_want.read())
+
+
+ # Filenames to test cleaning up markdown image links.
+ test_markdown_filenames = [
+ [
+ "tests/markdown_example_bad_image_links.md",
+ "tests/markdown_example_bad_image_links_want.md"
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_clean_image_links(self, base_filename, want_filename):
+ # Ensure image links are well formed in markdown files.
+
+ # Copy the base file we'll need to test.
+ with tempfile.NamedTemporaryFile(mode='r+', delete=False) as test_file:
+ with open(base_filename) as base_file:
+ # Use same file name extraction as original code.
+ file_name = base_file.name.split("/")[-1].split(".")[0].capitalize()
+ test_file.write(base_file.read())
+ test_file.flush()
+ test_file.seek(0)
+
+ markdown_utils._clean_image_links(test_file.name)
+ test_file.seek(0)
+
+ with open(want_filename) as mdfile_want:
+ self.assertEqual(test_file.read(), mdfile_want.read())
+
+
+ test_markdown_content = [
+ [
+ """The resource name or `None`
+
+if no Cloud KMS key was used, or the blob's resource has not been loaded from the server.
+
+For example:
+```
+ kms_key_name: ID
+```
+ """,
+ """The resource name or None
+
+if no Cloud KMS key was used, or the blob's resource has not been loaded from the server.
+
+For example:
+
+ kms_key_name: ID
+
+ """,
+ ],
+ ]
+ @parameterized.expand(test_markdown_content)
+ def test_reformat_markdown_to_html(self, content, content_want):
+ content_got = markdown_utils.reformat_markdown_to_html(content)
+ self.assertEqual(content_want, content_got)
+
+
+ test_markdown_content = [
+ [
+ # Test for simple header_line.
+ "# Test header",
+ "Test header",
+ "",
+ ],
+ [
+ # Test for invalid input.
+ "#Test header",
+ "",
+ "",
+ ],
+ [
+ # Test for invalid input.
+ "# Test header",
+ "",
+ "",
+ ],
+ [
+ # Test for no header.
+ "-->",
+ "",
+ "limitations under the license.\n",
+ ],
+ [
+ # Test for simple alternate header.
+ "============\n",
+ "Test header",
+ "Test header",
+ ],
+ [
+ # Test for no header.
+ "============\n",
+ "",
+ "",
+ ],
+ [
+ # Test for shorter divider.
+ "======\n",
+ "Test header",
+ "Test header",
+ ],
+ ]
+ @parameterized.expand(test_markdown_content)
+ def test_parse_markdown_header(self, header_line, header_line_want, prev_line):
+ header_line_got = markdown_utils._parse_markdown_header(header_line, prev_line)
+
+ self.assertEqual(header_line_got, header_line_want)
+
+
+ test_markdown_filenames = [
+ [
+ # Check the header for a normal markdown file.
+ "tests/markdown_example.md"
+ ],
+ [
+ # The header should be the same even with the license header.
+ "tests/markdown_example_header.md"
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_extract_header_from_markdown(self, markdown_filename):
+ # Check the header for markdown files.
+ header_line_want = "Test header for a simple markdown file."
+
+ with open(markdown_filename, 'r') as mdfile:
+ header_line_got = markdown_utils._extract_header_from_markdown(mdfile)
+
+ self.assertEqual(header_line_got, header_line_want)
+
+
+ test_markdown_filenames = [
+ [
+ # Check the header for an alternate header style.
+ "tests/markdown_example_alternate.md"
+ ],
+ [
+ # The header should be the same even with the license header.
+ "tests/markdown_example_alternate_header.md"
+ ],
+ [
+ # Check the header for an alternate header style.
+ "tests/markdown_example_alternate_less.md"
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_extract_header_from_markdown_alternate_header(self, markdown_filename):
+ # Check the header for different accepted styles.
+ header_line_want = "This is a simple alternate header"
+
+ with open(markdown_filename, 'r') as mdfile:
+ header_line_got = markdown_utils._extract_header_from_markdown(mdfile)
+
+ self.assertEqual(header_line_got, header_line_want)
+
+
+ test_markdown_filenames = [
+ [
+ "tests/markdown_example_bad_header.md"
+ ],
+ [
+ "tests/markdown_example_h2.md"
+ ],
+ [
+ "tests/markdown_example_alternate_bad.md"
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_extract_header_from_markdown_bad_headers(self, markdown_filename):
+ # Check that empty string is returned if no valid header is found.
+ with open(markdown_filename, 'r') as mdfile:
+ header_line_got = markdown_utils._extract_header_from_markdown(mdfile)
+
+ self.assertFalse(header_line_got)
+
+
+ def test_remove_unused_pages(self):
+ # Check that pages are removed as expected.
+ added_page = ['safe.md']
+ all_pages = ['to_delete.md', 'safe.md']
+ outdir = pathlib.Path('output_path')
+
+ expected_delete_call = f"{outdir}/to_delete.md"
+
+ with patch('os.remove') as mock_os_remove:
+ markdown_utils.remove_unused_pages(added_page, all_pages, outdir)
+ mock_os_remove.assert_called_once_with(expected_delete_call)
+
+
+ def test_remove_unused_pages_with_exception(self):
+ # Check that the method still runs as expected.
+ added_page = ['safe.md']
+ all_pages = ['does_not_exist.md', 'safe.md']
+ outdir = pathlib.Path('output_path')
+
+ self.assertFalse(os.path.isfile(outdir / 'does_not_exist.md'))
+
+ try:
+ markdown_utils.remove_unused_pages(added_page, all_pages, outdir)
+ except FileNotFoundError:
+ pytest.fail('Should not have thrown an exception.')
+
+
+ test_markdown_filenames = [
+ [
+ "tests/markdown_example_header.md",
+ "tests/markdown_example_header_want.md",
+ ],
+ [
+ "tests/markdown_example_header_with_comments.md",
+ "tests/markdown_example_header_with_comments_want.md",
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_remove_license(self, base_filename, want_filename):
+ # Check that licenses are correctly removed.
+
+ # Copy the base file we'll need to test.
+ with tempfile.NamedTemporaryFile(mode='w+', delete=False) as test_file:
+ with open(base_filename) as base_file:
+ test_file.write(base_file.read())
+ test_file.flush()
+ test_file.seek(0)
+
+ markdown_utils._remove_license(test_file.name)
+ test_file.seek(0)
+
+ with open(want_filename) as mdfile_want:
+ self.assertEqual(test_file.read(), mdfile_want.read())
+
+
+ test_markdown_filenames = [
+ [
+ "tests/markdown_example_base.md",
+ "tests/markdown_example_additional_content.md",
+ "tests/markdown_example_base_expected.md",
+ ],
+ [
+ # The content should be the same as base, and not throw any errors.
+ "tests/markdown_example_base.md",
+ "tests/markdown_example_does_not_exist.md",
+ "tests/markdown_example_base.md",
+ ],
+ [
+ # The content should be the same as base, and not throw any errors.
+ "tests/markdown_example_base.md",
+ "tests/markdown_example_additional_content.md",
+ "tests/markdown_example_prepended_base.md",
+ True,
+ ],
+ ]
+ @parameterized.expand(test_markdown_filenames)
+ def test_merges_markdown_content(
+ self,
+ base_file,
+ additional_file,
+ expected_file,
+ prepend_additional_content=False,
+ ):
+ with tempfile.NamedTemporaryFile(mode='w+', delete=False) as test_file:
+ with open(base_file) as base:
+ test_file.write(base.read())
+ test_file.flush()
+ test_file.seek(0)
+
+ markdown_utils._merge_markdown_content(
+ base_file=test_file.name,
+ additional_content_file=additional_file,
+ prepend_additional_content=prepend_additional_content,
+ )
+ test_file.seek(0)
+
+ with open(expected_file) as mdfile_expected:
+ self.assertEqual(test_file.read(), mdfile_expected.read())
+
+if __name__ == '__main__':
+ unittest.main()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/test_unit.py b/packages/gcp-sphinx-docfx-yaml/tests/test_unit.py
new file mode 100644
index 000000000000..73a0e66a7c15
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/test_unit.py
@@ -0,0 +1,1217 @@
+from docfx_yaml import extension
+
+import unittest
+from parameterized import parameterized
+
+from yaml import load, Loader
+
+class TestGenerate(unittest.TestCase):
+ def test_finds_unique_name(self):
+
+ entries = {}
+
+ # Disambiguate with unique entries.
+ schema_v1_entry = (
+ "google.cloud.aiplatform.v1.schema.predict.instance_v1.types"
+ )
+ schema_v1beta2_entry = (
+ "google.cloud.aiplatform.v1beta2.schema.predict.instance_v1.types"
+ )
+ for entry in [schema_v1_entry, schema_v1beta2_entry]:
+ for word in entry.split("."):
+ if word not in entries:
+ entries[word] = 1
+ else:
+ entries[word] += 1
+
+ unique_v1_name = extension.find_unique_name(
+ schema_v1_entry.split("."), entries
+ )
+ unique_v1beta2_name = extension.find_unique_name(
+ schema_v1beta2_entry.split("."), entries
+ )
+
+ self.assertEqual("v1.types", ".".join(unique_v1_name))
+ self.assertEqual("v1beta2.types", ".".join(unique_v1beta2_name))
+
+
+ test_entries = [
+ [
+ "tests/yaml_pre.yaml",
+ "tests/yaml_post.yaml",
+ {
+ "google.cloud.spanner_admin_database_v1.types": "spanner_admin_database_v1.types",
+ "google.cloud.spanner_admin_instance_v1.types": "spanner_admin_instance_v1.types",
+ "google.cloud.spanner_v1.types": "spanner_v1.types",
+ },
+ ],
+ [
+ # Tests duplicate names
+ "tests/yaml_pre_duplicate.yaml",
+ "tests/yaml_post_duplicate.yaml",
+ {
+ "google.api_core.client_info": "client_info",
+ "google.api_core.gapic_v1.client_info": "gapic_v1.client_info",
+ },
+ ],
+ [
+ # Tests repeated duplicates in a row. No changes expected.
+ "tests/yaml_repeat_duplicate.yaml",
+ "tests/yaml_repeat_duplicate.yaml",
+ {},
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_disambiguates_toc_name(
+ self,
+ test_filename,
+ expected_filename,
+ expected_disambiguated_names,
+ ):
+ with open(test_filename, "r") as test_file:
+ test_yaml = load(test_file, Loader=Loader)
+ with open(expected_filename, "r") as expected_yaml_file:
+ expected_yaml = load(expected_yaml_file, Loader=Loader)
+
+ disambiguated_names = extension.disambiguate_toc_name(
+ test_yaml
+ )
+
+ self.assertEqual(expected_yaml, test_yaml)
+ self.assertEqual(expected_disambiguated_names, disambiguated_names)
+
+ test_entries = [
+ [
+ """
+If a ``stream`` is attached to this download, then the downloaded
+resource will be written to the stream.
+
+Args:
+ transport (~google.cloud.requests.Session): A ``requests`` object which can
+ make authenticated requests.
+
+ timeout (Optional[Union[float, Tuple[float, float]]]):
+ The number of seconds to wait for the server response.
+ Depending on the retry strategy, a request may be repeated
+ several times using the same timeout each time.
+
+ Can also be passed as a tuple (connect_timeout, read_timeout).
+ See :meth:`google.cloud.requests.Session.request` documentation for details.
+
+Returns:
+ ~google.cloud.requests.Response: The HTTP response returned by ``transport``.
+
+Raises:
+ ~google.cloud.resumable_media.common.DataCorruption: If the download"s
+ checksum doesn't agree with server-computed checksum.
+ ValueError: If the current :class:`Download` has already
+ finished.
+ """,
+ """
+If a ``stream`` is attached to this download, then the downloaded
+resource will be written to the stream.
+
+Args:
+ transport (Session ): A ``requests`` object which can
+ make authenticated requests.
+
+ timeout (Optional[Union[float, Tuple[float, float]]]):
+ The number of seconds to wait for the server response.
+ Depending on the retry strategy, a request may be repeated
+ several times using the same timeout each time.
+
+ Can also be passed as a tuple (connect_timeout, read_timeout).
+ See request documentation for details.
+
+Returns:
+ Response : The HTTP response returned by ``transport``.
+
+Raises:
+ DataCorruption : If the download"s
+ checksum doesn't agree with server-computed checksum.
+ ValueError: If the current `Download` has already
+ finished.
+ """,
+ [
+ "google.cloud.requests.Session",
+ "google.cloud.requests.Session.request",
+ "google.cloud.requests.Response",
+ "google.cloud.resumable_media.common.DataCorruption",
+ ],
+ ],
+ [
+ """
+If a ~dateutil.time.stream() is attached to this download, then the downloaded
+resource will be written to the stream.
+
+Args:
+ transport (~google.cloud.requests.Session()): A ``requests`` object which can
+ make authenticated requests.
+
+ timeout (Optional[Union[float, Tuple[float, float]]]):
+ The number of seconds to wait for the server response.
+ Depending on the retry strategy, a request may be repeated
+ several times using the same timeout each time.
+
+ Can also be passed as a :func:`~google.cloud.requests.tuple()` (connect_timeout, read_timeout).
+ See :meth:`google.cloud.requests.Session.request()` documentation for details.
+ """,
+ """
+If a `dateutil.time.stream()` is attached to this download, then the downloaded
+resource will be written to the stream.
+
+Args:
+ transport (Session() ): A ``requests`` object which can
+ make authenticated requests.
+
+ timeout (Optional[Union[float, Tuple[float, float]]]):
+ The number of seconds to wait for the server response.
+ Depending on the retry strategy, a request may be repeated
+ several times using the same timeout each time.
+
+ Can also be passed as a tuple() (connect_timeout, read_timeout).
+ See request() documentation for details.
+ """,
+ [
+ "google.cloud.requests.Session",
+ "google.cloud.requests.tuple",
+ "google.cloud.requests.Session.request",
+ ],
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_resolves_references_in_summary(
+ self,
+ test_docstring,
+ expected_content,
+ expected_xrefs,
+ ):
+ xrefs_to_check = []
+ # Resolve over different regular expressions for different types of reference patterns.
+ content_to_resolve, xrefs = (
+ extension._resolve_reference_in_module_summary(
+ extension.REF_PATTERN,
+ test_docstring.split("\n"),
+ )
+ )
+ xrefs_to_check.extend(xrefs)
+
+ resolved_content, xrefs = (
+ extension._resolve_reference_in_module_summary(
+ extension.REF_PATTERN_LAST,
+ content_to_resolve,
+ )
+ )
+ xrefs_to_check.extend(xrefs)
+
+ self.assertEqual(resolved_content, expected_content.split("\n"))
+ self.assertCountEqual(xrefs_to_check, expected_xrefs)
+
+
+ test_entries = [
+ [
+ """Required.
+
+The [name][google.cloud.kms.v1.KeyRing.name] of the [KeyRing][google.cloud.kms.v1.KeyRing] associated with the [ImportJobs][google.cloud.kms.v1.ImportJob].
+ """,
+ """Required.
+
+The name of the KeyRing associated with the ImportJobs .
+ """,
+ [
+ "google.cloud.kms.v1.KeyRing.name",
+ "google.cloud.kms.v1.KeyRing",
+ "google.cloud.kms.v1.ImportJob",
+ ],
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_resolves_square_bracket_references(
+ self,
+ summary,
+ expected_summary,
+ expected_xrefs,
+ ):
+ resolved_summary, xrefs = (
+ extension._resolve_reference_in_module_summary(
+ extension.REF_PATTERN_BRACKETS,
+ summary.split("\n"),
+ )
+ )
+
+ self.assertEqual(resolved_summary, expected_summary.split("\n"))
+ self.assertCountEqual(xrefs, expected_xrefs)
+
+
+ def test_raises_error_for_invalid_references(self):
+ with self.assertRaises(ValueError):
+ extension._resolve_reference_in_module_summary(
+ ".*",
+ "not a valid ref line".split("\n"),
+ )
+
+
+ test_entries = [
+ [
+ """
+Simple test for docstring.
+
+Args:
+ arg1(int): simple description.
+ arg2(str): simple description for `arg2`.
+
+Returns:
+ str: simple description for return value.
+
+Raises:
+ AttributeError: if `condition x`.
+ """,
+ "\nSimple test for docstring.\n\n",
+ {
+ "variables": {
+ "arg1": {
+ "var_type": "int",
+ "description": "simple description.",
+ },
+ "arg2": {
+ "var_type": "str",
+ "description": "simple description for `arg2`.",
+ },
+ },
+ "returns": [{
+ "var_type": "str",
+ "description": "simple description for return value.",
+ }],
+ "exceptions": [{
+ "var_type": "AttributeError",
+ "description": "if `condition x`.",
+ }],
+ },
+ ],
+ [
+ # Tests summary in mixed format
+ """
+Simple test for docstring.
+
+:type arg1: int
+:param arg1: simple description.
+:param arg2: simple description for `arg2`.
+:type arg2: str
+
+:rtype: str
+:returns: simple description for return value.
+
+:raises AttributeError: if `condition x`.
+ """,
+ "\nSimple test for docstring.\n\n",
+ {
+ "variables": {
+ "arg1": {
+ "var_type": "int",
+ "description": "simple description.",
+ },
+ "arg2": {
+ "var_type": "str",
+ "description": "simple description for `arg2`.",
+ },
+ },
+ "returns": [{
+ "var_type": "str",
+ "description": "simple description for return value.",
+ }],
+ "exceptions": [{
+ "var_type": "AttributeError",
+ "description": "if `condition x`.",
+ }],
+ },
+
+ ],
+ [
+ # Tests summary for docstring tokens and not custom fields
+ """
+Union[int, None]: Expiration time in milliseconds for a partition.
+
+If :attr:`partition_expiration` is set and is
+not set, :attr:`type_` will default to
+:attr:`~google.cloud.bigquery.table.TimePartitioningType.DAY`.
+It could return :param: with :returns as well.
+ """,
+ """
+Union[int, None]: Expiration time in milliseconds for a partition.
+
+If :attr:`partition_expiration` is set and is
+not set, :attr:`type_` will default to
+:attr:`~google.cloud.bigquery.table.TimePartitioningType.DAY`.
+It could return :param: with :returns as well.
+ """,
+ {
+ "variables": {},
+ "returns": [],
+ "exceptions": [],
+ }
+ ],
+ [
+ # Tests summary with xrefs
+ """
+Simple test for docstring.
+
+:type arg1: Type
+:param arg1: simple description.
+:param arg2: simple description for `arg2`.
+:type arg2: ~google.spanner_v1.type.dict
+
+:rtype: Pair
+:returns: simple description for return value.
+
+:raises SpannerException : if `condition x`.
+ """,
+ "\nSimple test for docstring.\n\n",
+ {
+ "variables": {
+ "arg1": {
+ "var_type": "Type ",
+ "description": "simple description.",
+ },
+ "arg2": {
+ "var_type": "~google.spanner_v1.type.dict",
+ "description": "simple description for `arg2`.",
+ },
+ },
+ "returns": [{
+ "var_type": "Pair ",
+ "description": "simple description for return value.",
+ }],
+ "exceptions": [{
+ "var_type": "SpannerException ",
+ "description": "if `condition x`.",
+ }],
+ },
+ ],
+ [
+ # Tests docstring without a summary
+ """
+Args:
+ arg1(int): simple description.
+ arg2(str): simple description for `arg2`.
+
+Returns:
+ str: simple description for return value.
+
+Raises:
+ AttributeError: if `condition x`.
+ """,
+ "\n",
+ {
+ "variables": {
+ "arg1": {
+ "var_type": "int",
+ "description": "simple description.",
+ },
+ "arg2": {
+ "var_type": "str",
+ "description": "simple description for `arg2`.",
+ },
+ },
+ "returns": [{
+ "var_type": "str",
+ "description": "simple description for return value.",
+ }],
+ "exceptions": [{
+ "var_type": "AttributeError",
+ "description": "if `condition x`.",
+ }],
+ },
+
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_extracts_docstring_info(
+ self,
+ summary,
+ expected_top_summary,
+ expected_summary_info
+ ):
+ summary_info = {
+ "variables": {},
+ "returns": [],
+ "exceptions": []
+ }
+
+ top_summary = extension._extract_docstring_info(
+ summary_info,
+ summary,
+ "",
+ )
+
+ self.assertEqual(top_summary, expected_top_summary)
+ self.assertDictEqual(summary_info, expected_summary_info)
+
+
+ test_entries = [
+ [
+ """
+Description of docstring which should fail.
+
+:returns:param:
+ """,
+ ValueError,
+ "Error string",
+ ],
+ [
+ """
+Description of malformed docstring.
+
+Raises:
+ Error that should fail: if condition `x`.
+ """,
+ KeyError,
+ "Malformed docstring",
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_raises_error_extracting_malformed_docstring(
+ self,
+ summary,
+ error_type,
+ error_string,
+ ):
+ with self.assertRaises(error_type):
+ extension._extract_docstring_info({}, summary, error_string)
+
+
+ test_entries = [
+ [
+ "google.cloud.spanner_v1beta2.services.admin_database_v1.types",
+ "google.cloud.spanner_v1beta2",
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_finds_package_group(
+ self,
+ uid,
+ expected_package_group,
+ ):
+ package_group = extension.find_package_group(uid)
+
+ self.assertEqual(package_group, expected_package_group)
+
+
+ test_entries = [
+ [
+ "google.cloud.spanner_v1beta2",
+ "Spanner V1beta2",
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_finds_pretty_package_name(
+ self,
+ package_group,
+ expected_package_name,
+ ):
+ package_name = extension.pretty_package_name(package_group)
+
+ self.assertEqual(package_name, expected_package_name)
+
+
+ test_entries = [
+ [
+ # toc_yaml entry
+ [{
+ "name":"database_admin",
+ "uidname":"google.cloud.spanner_admin_database_v1.services.database_admin",
+ "items":[
+ {
+ "name":"Overview",
+ "uidname":"google.cloud.spanner_admin_database_v1.services.database_admin",
+ "uid":"google.cloud.spanner_admin_database_v1.services.database_admin"
+ },
+ {
+ "name":"ListBackupOperationsAsyncPager",
+ "uidname":"google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListBackupOperationsAsyncPager",
+ "uid":"google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListBackupOperationsAsyncPager"
+ }
+ ]
+ },
+ {
+ "name":"spanner_admin_database_v1.types",
+ "uidname":"google.cloud.spanner_admin_database_v1.types",
+ "items":[
+ {
+ "name":"Overview",
+ "uidname":"google.cloud.spanner_admin_database_v1.types",
+ "uid":"google.cloud.spanner_admin_database_v1.types"
+ },
+ {
+ "name":"BackupInfo",
+ "uidname":"google.cloud.spanner_admin_database_v1.types.BackupInfo",
+ "uid":"google.cloud.spanner_admin_database_v1.types.BackupInfo"
+ }
+ ]
+ },
+ {
+ "name":"pool",
+ "uidname":"google.cloud.spanner_v1.pool",
+ "items":[
+ {
+ "name":"Overview",
+ "uidname":"google.cloud.spanner_v1.pool",
+ "uid":"google.cloud.spanner_v1.pool"
+ },
+ {
+ "name":"AbstractSessionPool",
+ "uidname":"google.cloud.spanner_v1.pool.AbstractSessionPool",
+ "uid":"google.cloud.spanner_v1.pool.AbstractSessionPool"
+ }
+ ]
+ }],
+ # expected_toc_yaml entry
+ [
+ {
+ "name": "Spanner Admin Database V1",
+ "uidname":"google.cloud.spanner_admin_database_v1",
+ "items": [{
+ "name":"database_admin",
+ "uidname":"google.cloud.spanner_admin_database_v1.services.database_admin",
+ "items": [{
+ "name":"Overview",
+ "uidname":"google.cloud.spanner_admin_database_v1.services.database_admin",
+ "uid":"google.cloud.spanner_admin_database_v1.services.database_admin"
+ },
+ {
+ "name":"ListBackupOperationsAsyncPager",
+ "uidname":"google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListBackupOperationsAsyncPager",
+ "uid":"google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListBackupOperationsAsyncPager",
+ }],
+ },
+ {
+ "name":"spanner_admin_database_v1.types",
+ "uidname":"google.cloud.spanner_admin_database_v1.types",
+ "items": [{
+ "name":"Overview",
+ "uidname":"google.cloud.spanner_admin_database_v1.types",
+ "uid":"google.cloud.spanner_admin_database_v1.types",
+ },
+ {
+ "name":"BackupInfo",
+ "uidname":"google.cloud.spanner_admin_database_v1.types.BackupInfo",
+ "uid":"google.cloud.spanner_admin_database_v1.types.BackupInfo",
+ }],
+ }],
+ },
+ {
+ "name": "Spanner V1",
+ "uidname":"google.cloud.spanner_v1",
+ "items": [{
+ "name":"pool",
+ "uidname":"google.cloud.spanner_v1.pool",
+ "items": [{
+ "name":"Overview",
+ "uidname":"google.cloud.spanner_v1.pool",
+ "uid":"google.cloud.spanner_v1.pool"
+ },
+ {
+ "name":"AbstractSessionPool",
+ "uidname":"google.cloud.spanner_v1.pool.AbstractSessionPool",
+ "uid":"google.cloud.spanner_v1.pool.AbstractSessionPool",
+ }],
+ }],
+ },
+ ],
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_groups_by_package(
+ self,
+ toc_yaml,
+ expected_toc_yaml,
+ ):
+ toc_yaml = extension.group_by_package(toc_yaml)
+
+ self.assertCountEqual(toc_yaml, expected_toc_yaml)
+
+
+ test_entries = [
+ [
+ (\
+"""
+
+
+.. code-block:: python
+
+\n from google.api_core.client_options import ClientOptions
+\n from google.cloud.vision_v1 import ImageAnnotatorClient
+\n def get_client_cert():
+\n # code to load client certificate and private key.
+\n return client_cert_bytes, client_private_key_bytes
+\n options = ClientOptions(api_endpoint=\"foo.googleapis.com\",
+\n client_cert_source=get_client_cert)
+\n client = ImageAnnotatorClient(client_options=options)
+
+
+You can also pass a mapping object.
+
+
+\n.. code-block:: ruby
+
+\n from google.cloud.vision_v1 import ImageAnnotatorClient
+\n client = ImageAnnotatorClient(
+\n client_options={
+\n \"api_endpoint\": \"foo.googleapis.com\",
+\n \"client_cert_source\" : get_client_cert
+\n })
+"""
+ ),
+ (\
+"""```python
+from google.api_core.client_options import ClientOptions
+
+from google.cloud.vision_v1 import ImageAnnotatorClient
+
+def get_client_cert():
+
+ # code to load client certificate and private key.
+
+ return client_cert_bytes, client_private_key_bytes
+
+options = ClientOptions(api_endpoint=\"foo.googleapis.com\",
+
+ client_cert_source=get_client_cert)
+
+client = ImageAnnotatorClient(client_options=options)
+```
+
+You can also pass a mapping object.
+
+```ruby
+from google.cloud.vision_v1 import ImageAnnotatorClient
+
+client = ImageAnnotatorClient(
+
+ client_options={
+
+ \"api_endpoint\": \"foo.googleapis.com\",
+
+ \"client_cert_source\" : get_client_cert
+
+ })
+
+```
+"""
+ ),
+ ],
+ [
+ # Check that nothing changes for literalincludes.
+ (\
+"""
+.. literalinclude::
+ note that these are not supported yet, so they will be ignored for now.
+
+And any other documentation that the source code would have could go here.
+"""
+ ),
+ (\
+"""
+.. literalinclude::
+ note that these are not supported yet, so they will be ignored for now.
+
+And any other documentation that the source code would have could go here.
+
+"""
+ ),
+ ],
+ [
+ # Tests notices are processed properly.
+ (\
+"""
+.. note::
+\n this is a note.
+
+
+.. caution::
+\n another type of notice.
+
+
+.. key-term::
+\n hyphenated term notice.
+"""
+ ),
+ (\
+"""
+Note:
+this is a note.
+
+
+Caution:
+another type of notice.
+
+
+Key Term:
+hyphenated term notice.
+ """
+ ),
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_parses_docstring_summary(
+ self,
+ summary,
+ expected_summary,
+ ):
+ parsed_summary, attributes, enums = (
+ extension._parse_docstring_summary(summary)
+ )
+ self.assertEqual(parsed_summary, expected_summary)
+ self.assertEqual(attributes, [])
+ self.assertEqual(enums, [])
+
+
+ test_entries = [
+ [
+ (\
+"""
+
+
+.. code:: python
+
+\nprint("This should throw an exception.")
+\nfor i in range(10):
+\n print(i)
+"""
+ ),
+ ValueError,
+ ],
+ [
+ (\
+"""
+.. warning::
+this is not a properly formatted warning.
+"""
+ ),
+ ValueError,
+ ],
+ [
+ (\
+"""
+Values:
+BAD_FORMATTING (-1): this is not properly formatted enum.
+"""
+ ),
+ ValueError,
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_raises_error_parsing_malformed_docstring(
+ self,
+ summary,
+ error_type
+ ):
+ with self.assertRaises(error_type):
+ extension._parse_docstring_summary(summary)
+
+
+ test_entries = [
+ [
+ (\
+"""
+
+
+.. attribute:: simple name
+
+\nsimple description
+
+\n:type: str
+"""
+ ),
+ [{
+ "id": "simple name",
+ "description": "simple description",
+ "var_type": "str",
+ }],
+ [],
+ ],
+ [
+ # Tests for multiple attributes.
+ (\
+"""
+
+
+.. attribute:: simple name
+
+\nsimple description
+
+\n:type: str
+
+
+.. attribute:: table_insert_request
+
+\nTable insert request.
+
+\n:type: google.cloud.bigquery_logging_v1.types.TableInsertRequest
+"""
+ ),
+ [{
+ "id": "simple name",
+ "description": "simple description",
+ "var_type": "str",
+ },
+ {
+ "id": "table_insert_request",
+ "description": "Table insert request.",
+ "var_type": "google.cloud.bigquery_logging_v1.types.TableInsertRequest",
+ }],
+ [],
+ ],
+ [
+ # Tests only attributes in valid format are parsed.
+ (\
+"""
+
+
+.. attribute:: table_insert_request
+
+\nTable insert request.
+
+\ntype: google.cloud.bigquery_logging_v1.types.TableInsertRequest
+
+
+.. attribute:: proper name
+
+\nproper description.
+
+\n:type: str
+"""
+ ),
+ [{
+ "id": "proper name",
+ "description": "proper description.",
+ "var_type": "str",
+ }],
+ [],
+ ],
+ [
+ # Tests enums are parsed.
+ (\
+"""
+Values:
+ EMPLOYMENT_TYPE_UNSPECIFIED (0):
+ The default value if the employment type isn't specified.
+ FULL_TIME (1):
+ The job requires working a number of hours that constitute full time
+ employment, typically 40 or more hours per week.
+ PART_TIME (2):
+ The job entails working fewer hours than a full time job,
+ typically less than 40 hours a week.
+"""
+ ),
+ [],
+ [
+ {
+ "id": "EMPLOYMENT_TYPE_UNSPECIFIED",
+ "description": (
+ "The default value if the employment type isn't"
+ " specified."
+ ),
+ },
+ {
+ "id": "FULL_TIME",
+ "description": (
+ "The job requires working a number of hours that"
+ " constitute full time employment, typically 40 or"
+ " more hours per week."
+ ),
+ },
+ {
+ "id": "PART_TIME",
+ "description": (
+ "The job entails working fewer hours than a full"
+ " time job, typically less than 40 hours a week."
+ ),
+ },
+
+ ],
+ ],
+ ]
+ @parameterized.expand(test_entries)
+ def test_parses_docstring_summary_for_attributes_and_enums(
+ self,
+ summary,
+ expected_attributes,
+ expected_enums,
+ ):
+ _, attributes, enums = extension._parse_docstring_summary(summary)
+
+ self.assertCountEqual(attributes, expected_attributes)
+ self.assertCountEqual(enums, expected_enums)
+
+ for attribute, expected_attribute in zip(
+ attributes, expected_attributes
+ ):
+ self.assertDictEqual(attribute, expected_attribute)
+ for enum, expected_enum in zip(
+ enums, expected_enums
+ ):
+ self.assertDictEqual(enum, expected_enum)
+
+
+ def test_merges_markdown_and_package_toc(self):
+ known_uids = {
+ "acl",
+ "batch",
+ "blob",
+ "client",
+ "constants",
+ "fileio",
+ "hmac_key",
+ "notification",
+ "retry",
+ }
+ markdown_pages = {
+ "storage": [
+ {"name": "FileIO", "href": "fileio.md"},
+ {"name": "Retry", "href": "retry.md"},
+ {"name": "Notification", "href": "notification.md"},
+ {"name": "HMAC Key Metadata", "href": "hmac_key.md"},
+ {"name": "Batches", "href": "batch.md"},
+ {"name": "Constants", "href": "constants.md"},
+ {"name": "Storage Client", "href": "client.md"},
+ {"name": "Blobs / Objects", "href": "blobs.md"}
+ ],
+ "acl": [
+ {"name": "ACL", "href": "acl.md"},
+ {"name": "ACL guide", "href": "acl_guide.md"}
+ ],
+ "/": [
+ {"name": "Overview", "href": "index.md"},
+ {"name": "Changelog", "href": "changelog.md"}
+ ],
+ }
+ pkg_toc_yaml = [
+ {"name": "Storage",
+ "items": [
+ {
+ "name": "acl",
+ "uid": "google.cloud.storage.acl",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.acl",
+ },
+ ],
+ },
+ {
+ "name": "batch",
+ "uid": "google.cloud.storage.batch",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.batch",
+ },
+ ],
+ },
+ {
+ "name": "blob",
+ "uid": "google.cloud.storage.blob",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.blob",
+ },
+ ],
+ },
+ {
+ "name": "bucket",
+ "uid": "google.cloud.storage.bucket",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.bucket",
+ },
+ ],
+ },
+ {
+ "name": "client",
+ "uid": "google.cloud.storage.client",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.client",
+ },
+ ],
+ },
+ {
+ "name": "constants",
+ "uid": "google.cloud.storage.constants",
+ },
+ {
+ "name": "fileio",
+ "uid": "google.cloud.storage.fileio",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.fileio",
+ },
+ ],
+ },
+ {
+ "name": "hmac_key",
+ "uid": "google.cloud.storage.hmac_key",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.hmac_key",
+ },
+ ],
+ },
+ {
+ "name": "notification",
+ "uid": "google.cloud.storage.notification",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.notification"},
+ ],
+ },
+ {
+ "name": "retry",
+ "uid": "google.cloud.storage.retry",
+ "items": [
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.retry",
+ },
+ ],
+ },
+ ],
+ },
+ ]
+
+ added_pages, merged_pkg_toc_yaml = extension.merge_markdown_and_package_toc(
+ pkg_toc_yaml, markdown_pages, known_uids
+ )
+
+ expected_merged_pkg_toc_yaml = [
+ {"name": "Overview", "href": "index.md"},
+ {"name": "Changelog", "href": "changelog.md"},
+ {"name": "Storage",
+ "items": [
+ {"name": "Blobs / Objects", "href": "blobs.md"},
+ {"name": "acl", "uid": "google.cloud.storage.acl", "items": [
+ {"name": "ACL guide", "href": "acl_guide.md"},
+ {"name": "Overview", "uid": "google.cloud.storage.acl"},
+ ]},
+ {"name": "batch", "uid": "google.cloud.storage.batch", "items": [{"name": "Overview", "uid": "google.cloud.storage.batch"}]},
+ {"name": "blob", "uid": "google.cloud.storage.blob", "items": [{"name": "Overview", "uid": "google.cloud.storage.blob"}]},
+ {"name": "bucket", "uid": "google.cloud.storage.bucket", "items": [{"name": "Overview", "uid": "google.cloud.storage.bucket"}]},
+ {"name": "client", "uid": "google.cloud.storage.client", "items": [{"name": "Overview", "uid": "google.cloud.storage.client"}]},
+ {"name": "constants", "uid": "google.cloud.storage.constants"},
+ {"name": "fileio", "uid": "google.cloud.storage.fileio", "items": [{"name": "Overview", "uid": "google.cloud.storage.fileio"}]},
+ {"name": "hmac_key", "uid": "google.cloud.storage.hmac_key", "items": [{"name": "Overview", "uid": "google.cloud.storage.hmac_key"}]},
+ {"name": "notification", "uid": "google.cloud.storage.notification", "items": [{"name": "Overview", "uid": "google.cloud.storage.notification"}]},
+ {"name": "retry", "uid": "google.cloud.storage.retry", "items": [{"name": "Overview", "uid": "google.cloud.storage.retry"}]},
+ ]
+ },
+ ]
+ self.assertSetEqual(
+ added_pages,
+ {
+ "index.md",
+ "changelog.md",
+ "blobs.md",
+ "acl_guide.md",
+ }
+ )
+ self.assertListEqual(
+ merged_pkg_toc_yaml,
+ [
+ {"name": "Overview", "href": "index.md"},
+ {"name": "Changelog", "href": "changelog.md"},
+ {"name": "Storage",
+ "items": [
+ {"name": "Blobs / Objects", "href": "blobs.md"},
+ {
+ "name": "acl",
+ "uid": "google.cloud.storage.acl",
+ "items": [
+ {"name": "ACL guide", "href": "acl_guide.md"},
+ {
+ "name": "Overview",
+ "uid": "google.cloud.storage.acl",
+ },
+ ],
+ },
+ {
+ "name": "batch",
+ "uid": "google.cloud.storage.batch",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.batch",
+ }],
+ },
+ {
+ "name": "blob",
+ "uid": "google.cloud.storage.blob",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.blob",
+ }],
+ },
+ {
+ "name": "bucket",
+ "uid": "google.cloud.storage.bucket",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.bucket",
+ }],
+ },
+ {
+ "name": "client",
+ "uid": "google.cloud.storage.client",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.client",
+ }],
+ },
+ {
+ "name": "constants",
+ "uid": "google.cloud.storage.constants",
+ },
+ {
+ "name": "fileio",
+ "uid": "google.cloud.storage.fileio",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.fileio",
+ }],
+ },
+ {
+ "name": "hmac_key",
+ "uid": "google.cloud.storage.hmac_key",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.hmac_key",
+ }],
+ },
+ {
+ "name": "notification",
+ "uid": "google.cloud.storage.notification",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.notification",
+ }],
+ },
+ {
+ "name": "retry",
+ "uid": "google.cloud.storage.retry",
+ "items": [{
+ "name": "Overview",
+ "uid": "google.cloud.storage.retry",
+ }],
+ },
+ ],
+ },
+ ],
+ ),
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/CHANGELOG.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/CHANGELOG.md
new file mode 100644
index 000000000000..826433848004
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/CHANGELOG.md
@@ -0,0 +1,169 @@
+# Changelog
+
+[PyPI History][1]
+
+[1]: https://pypi.org/project/google-auth-oauthlib/#history
+
+## [1.0.0](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.8.0...v1.0.0) (2023-02-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* PKCE is enabled by default. ([#269](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/269))
+
+### Features
+
+* PKCE is enabled by default. ([#269](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/269)) ([1e04d3f](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/1e04d3f181b1734a73d82396c969754034f55b38))
+
+
+### Bug Fixes
+
+* Change the library from preview to stable ([#267](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/267)) ([c77edf1](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/c77edf12a84cc71622f25eee5091656652ff2c65))
+* Remove deprecated OOB code ([1391486](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/13914865ec3cbdb1e4ab87a7bcfc34d0b4e184d3))
+
+## [0.8.0](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.7.1...v0.8.0) (2022-12-08)
+
+
+### Features
+
+* Add support for Python 3.11 ([#253](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/253)) ([85fd1da](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/85fd1dab50a6cb387f11a4f00ad9ec6c49f7994c))
+* Introduce granted scopes to credentials ([#257](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/257)) ([51fef3b](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/51fef3b9703a292f39054f80d9bf9780d115db6c))
+
+## [0.7.1](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.7.0...v0.7.1) (2022-11-03)
+
+
+### Bug Fixes
+
+* Include updates to properties from Google Auth lib ([#249](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/249)) ([58becac](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/58becac1a4030d9bc3daf089645c4412227c4679))
+
+## [0.7.0](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.6.0...v0.7.0) (2022-10-25)
+
+
+### Bug Fixes
+
+* **setup.py:** increase required google-auth version to >=2.13.0 ([f8a15f7](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/f8a15f75115ed5ef3ea47b50a707459ed62a8f48))
+
+## [0.6.0](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.5.3...v0.6.0) (2022-10-20)
+
+
+### Features
+
+* Update to allow for 3PI credentials ([#240](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/240)) ([4a37dec](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/4a37dec027e3d742ed6615f9828ab51a594d2ca2))
+
+
+### Bug Fixes
+
+* Add timeout to run_local_server when waiting for response ([#245](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/245)) ([8d53bc3](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/8d53bc304a079d011df2757be1b88211baf47549))
+
+
+### Documentation
+
+* Update readme to point to current docs url ([#241](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/241)) ([8c29d2e](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/8c29d2ed0d8fda7319617fdd6ac2cde70319b6bd))
+
+## [0.5.3](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.5.2...v0.5.3) (2022-09-02)
+
+
+### Bug Fixes
+
+* Pass port range from `get_user_credentials` to `find_open_port` ([#212](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/212)) ([479330a](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/479330a49a28e4f7443982ba235d2adee3e49d58))
+
+## [0.5.2](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.5.1...v0.5.2) (2022-06-03)
+
+
+### Documentation
+
+* fix changelog header to consistent size ([#204](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/204)) ([cbd7d67](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/cbd7d675e772ad7c31da45296e3444113b6fd19a))
+
+## [0.5.1](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.5.0...v0.5.1) (2022-03-15)
+
+
+### Bug Fixes
+
+* avoid deprecated "out-of-band" authentication flow ([#186](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/186)) ([f119c4e](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/f119c4e0f5cad25b1254b0783e8226eda2d361cb))
+
+## [0.5.0](https://github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.4.6...v0.5.0) (2022-02-24)
+
+
+### Features
+
+* deprecate OAuth out-of-band flow ([#175](https://github.com/googleapis/google-auth-library-python-oauthlib/issues/175)) ([1fb16be](https://github.com/googleapis/google-auth-library-python-oauthlib/commit/1fb16be1bad9050ee29293541be44e41e82defd7))
+
+## [0.4.6](https://www.github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.4.5...v0.4.6) (2021-08-30)
+
+
+### Bug Fixes
+
+* remove dependency on `six` ([#146](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/146)) ([c338733](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/c3387335c49597870b437a9130aed92dca6571f2)), closes [#145](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/145)
+
+## [0.4.5](https://www.github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.4.4...v0.4.5) (2021-07-26)
+
+
+### Documentation
+
+* fix links to installed app, client secrets docs ([#86](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/86)) ([e8e5dbb](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/e8e5dbbf0b118fc68a9b60b91f0075f84908b6f6)), closes [#85](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/85)
+* omit mention of Python 2.7 in 'CONTRIBUTING.rst' ([#1127](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/1127)) ([#126](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/126)) ([8806324](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/8806324428b5aebe6659c49a16066afafbe4d400)), closes [#1126](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/1126)
+* add Samples section to CONTRIBUTING.rst ([#134](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/134)) ([1599a97](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/1599a97831bbe1c15cf5a0d257817967c1cd227f))
+
+
+### Miscellaneous Chores
+
+* release as 0.4.5 ([#137](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/137)) ([a54f283](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/a54f283ee7854367ff289ee863a7404692f31099))
+
+## [0.4.4](https://www.github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.4.3...v0.4.4) (2021-03-29)
+
+
+### Bug Fixes
+
+* add redirect_uri_trailing slash param to run_local_server ([#111](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/111)) ([666863a](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/666863aeabb8d6b3608ea95edce09fe69a5f2679))
+
+## [0.4.3](https://www.github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.4.2...v0.4.3) (2021-02-12)
+
+
+### Bug Fixes
+
+* add `charset-utf-8` to response header ([#104](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/104)) ([53e31e2](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/53e31e2d03b315c12670370f67bdca29b1cd5422))
+* **deps:** add lower bounds to all dependencies ([#99](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/99)) ([5587c6a](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/5587c6a72547742986e363e1f5ef6bcabd93bb02))
+
+## [0.4.2](https://www.github.com/googleapis/google-auth-library-python-oauthlib/compare/v0.4.1...v0.4.2) (2020-10-28)
+
+
+### Bug Fixes
+
+* don't open browser if port is occupied ([#92](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/92)) ([0004057](https://www.github.com/googleapis/google-auth-library-python-oauthlib/commit/00040576ab096faec1f6eb54c886cb9c33be17ed)), closes [#75](https://www.github.com/googleapis/google-auth-library-python-oauthlib/issues/75)
+
+## 0.4.1
+
+08-26-2019 13:25 PDT
+
+### Implementation Changes
+- Don't auto-generate code_verifier by default. ([#48](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/48))
+
+### Internal / Testing Changes
+- Add renovate.json ([#56](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/56))
+
+## 0.4.0
+- Add `get_user_credentials` function to get your user credentials ([#40](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/40))
+- Add noxfile ([#43](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/43))
+- Implement code verifier (PKCE) ([#42](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/42))
+- Use actual server port in redirect_uri to allow automatic assignment ([#33](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/33))
+([#41](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/41))
+
+## 0.3.0
+- Use utc when parsing expiration timestamp ([#26](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/26))
+- Allow saving credentials in current directory ([#25](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/25))
+
+## 0.2.0
+- Populate id_token into credentials from oauth2session ([#20](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/20))
+- Carry token expiry from oauth2session into Credentials object ([#18](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/18)) ([#19](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/19))
+- Accept redirect_uri as arg to flow creating classmethods. ([#17](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/17))
+
+## 0.1.1
+- Allow ``access_type`` parameter to be overriden in ``Flow`` ([#16](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/16))
+- Use a test port that is less likely to be taken ([#12](https://github.com/googleapis/google-auth-library-python-oauthlib/pull/12))
+- Documentation updates
+
+## 0.1.0
+Add command line tool.
+
+## 0.0.1
+Initial release. This package contains the functionality previously located in `google.oauth2.oauthlib` and `google.oauth2.flows`.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/README.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/README.rst
new file mode 100644
index 000000000000..efe263f904d8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/README.rst
@@ -0,0 +1,50 @@
+oauthlib integration for Google Auth
+====================================
+
+|pypi|
+
+This library provides `oauthlib`_ integration with `google-auth`_.
+
+.. |build| image:: https://travis-ci.org/googleapis/google-auth-library-python-oauthlib.svg?branch=main
+ :target: https://googleapis.dev/python/google-auth-oauthlib/latest/index.html
+.. |pypi| image:: https://img.shields.io/pypi/v/google-auth-oauthlib.svg
+ :target: https://pypi.python.org/pypi/google-auth-oauthlib
+
+.. _oauthlib: https://github.com/idan/oauthlib
+.. _google-auth: https://github.com/googleapis/google-auth-library-python
+
+Installing
+----------
+
+You can install using `pip`_::
+
+ $ pip install google-auth-oauthlib
+
+.. _pip: https://pip.pypa.io/en/stable/
+
+Documentation
+-------------
+
+The latest documentation is available at `google-auth-oauthlib.googleapis.dev`_.
+
+.. _google-auth-oauthlib.googleapis.dev: https://googleapis.dev/python/google-auth-oauthlib/latest/index.html
+
+Supported Python Versions
+-------------------------
+Python >= 3.6
+
+
+Unsupported Python Versions
+---------------------------
+
+Python == 2.7, Python == 3.5.
+
+The last version of this library compatible with Python 2.7 and 3.5 is
+`google-auth-oauthlib==0.4.1`.
+
+License
+-------
+
+Apache 2.0 - See `the LICENSE`_ for more information.
+
+.. _the LICENSE: https://github.com/googleapis/google-auth-library-python-oauthlib/blob/main/LICENSE
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/_static/custom.css b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/_static/custom.css
new file mode 100644
index 000000000000..b0a295464b23
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/_static/custom.css
@@ -0,0 +1,20 @@
+div#python2-eol {
+ border-color: red;
+ border-width: medium;
+}
+
+/* Ensure minimum width for 'Parameters' / 'Returns' column */
+dl.field-list > dt {
+ min-width: 100px
+}
+
+/* Insert space between methods for readability */
+dl.method {
+ padding-top: 10px;
+ padding-bottom: 10px
+}
+
+/* Insert empty space between classes */
+dl.class {
+ padding-bottom: 50px
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/_templates/layout.html b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/_templates/layout.html
new file mode 100644
index 000000000000..6316a537f72b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/_templates/layout.html
@@ -0,0 +1,50 @@
+
+{% extends "!layout.html" %}
+{%- block content %}
+{%- if theme_fixed_sidebar|lower == 'true' %}
+
+ {{ sidebar() }}
+ {%- block document %}
+
+ {%- if render_sidebar %}
+
+ {%- endif %}
+
+ {%- block relbar_top %}
+ {%- if theme_show_relbar_top|tobool %}
+
+
+ {{- rellink_markup () }}
+
+ {%- endif %}
+ {% endblock %}
+
+
+
+ As of January 1, 2020 this library no longer supports Python 2 on the latest released version.
+ Library versions released prior to that date will continue to be available. For more information please
+ visit
Python 2 support on Google Cloud .
+
+ {% block body %} {% endblock %}
+
+
+ {%- block relbar_bottom %}
+ {%- if theme_show_relbar_bottom|tobool %}
+
+
+ {{- rellink_markup () }}
+
+ {%- endif %}
+ {% endblock %}
+
+ {%- if render_sidebar %}
+
+ {%- endif %}
+
+ {%- endblock %}
+
+
v documentation".
+# html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a
+
+This library contains experimental `oauthlib`_ integration with `google-auth`_.
+
+.. _oauthlib: https://oauthlib.readthedocs.io
+.. _google-auth: https://google-auth.readthedocs.io
+
+Installing
+----------
+
+google-auth can be installed with `pip`_::
+
+ $ pip install --upgrade google-auth-oauthlib
+
+google-auth-oauthlib is open-source, so you can alternatively grab the source
+code from `GitHub`_ and install from source.
+
+.. _pip: https://pip.pypa.io
+.. _GitHub:
+ https://github.com/GoogleCloudPlatform/google-auth-library-python-oauthlib
+
+Usage
+-----
+
+Consult the :doc:`Module Reference ` documentation.
+
+License
+-------
+
+google-auth-oauthlib is made available under the Apache License, Version 2.0.
+For more details, see `LICENSE`_
+
+.. _LICENSE:
+ https://github.com/GoogleCloudPlatform/google-auth-library-python-oauthlib/LICENSE
+
+Contributing
+------------
+
+We happily welcome contributions, please see our `contributing`_ documentation
+for details.
+
+.. _contributing:
+ https://github.com/GoogleCloudPlatform/google-auth-library-python/CONTRIBUTING.rst
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.flow.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.flow.rst
new file mode 100644
index 000000000000..f4646640d030
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.flow.rst
@@ -0,0 +1,7 @@
+google\_auth\_oauthlib\.flow module
+===================================
+
+.. automodule:: google_auth_oauthlib.flow
+ :members:
+ :inherited-members:
+ :show-inheritance:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.helpers.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.helpers.rst
new file mode 100644
index 000000000000..03807871cba1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.helpers.rst
@@ -0,0 +1,7 @@
+google\_auth\_oauthlib\.helpers module
+======================================
+
+.. automodule:: google_auth_oauthlib.helpers
+ :members:
+ :inherited-members:
+ :show-inheritance:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.rst
new file mode 100644
index 000000000000..309e960d4593
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.rst
@@ -0,0 +1,23 @@
+google\_auth\_oauthlib package
+==============================
+
+.. automodule:: google_auth_oauthlib
+ :members:
+ :inherited-members:
+ :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+
+ google_auth_oauthlib.tool
+
+Submodules
+----------
+
+.. toctree::
+
+ google_auth_oauthlib.flow
+ google_auth_oauthlib.helpers
+
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.tool.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.tool.rst
new file mode 100644
index 000000000000..6f7ad12ce542
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/google_auth_oauthlib.tool.rst
@@ -0,0 +1,8 @@
+google\_auth\_oauthlib\.tool package
+====================================
+
+.. automodule:: google_auth_oauthlib.tool
+ :members:
+ :inherited-members:
+ :show-inheritance:
+
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/modules.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/modules.rst
new file mode 100644
index 000000000000..c8699655c950
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/docs/reference/modules.rst
@@ -0,0 +1,7 @@
+google_auth_oauthlib
+====================
+
+.. toctree::
+ :maxdepth: 4
+
+ google_auth_oauthlib
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/__init__.py
new file mode 100644
index 000000000000..1905f9a47070
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/__init__.py
@@ -0,0 +1,23 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""oauthlib integration for Google Auth
+
+This library provides `oauthlib `_. Learn more
+ with the `Authenticating as an end user
+ `_ guide.
+
+ Args:
+ scopes (Sequence[str]):
+ A list of scopes to use when authenticating to Google APIs. See
+ the `list of OAuth 2.0 scopes for Google APIs
+ `_.
+ client_id (str):
+ A string that identifies your application to Google APIs. Find
+ this value in the `Credentials page on the Google Developer's
+ Console
+ `_.
+ client_secret (str):
+ A string that verifies your application to Google APIs. Find this
+ value in the `Credentials page on the Google Developer's Console
+ `_.
+ minimum_port (int):
+ Beginning of range of ports to try for redirect URI HTTP server.
+ Defaults to 8080.
+ maximum_port (Optional[int]):
+ End of range of ports to try (not including exactly equals ``stop``).
+ This function tries 100 possible ports if no ``stop`` is specified.
+
+ Returns:
+ google.oauth2.credentials.Credentials:
+ The OAuth 2.0 credentials for the user.
+
+ Examples:
+ Get credentials for your user account and use them to run a query
+ with BigQuery::
+
+ import google_auth_oauthlib
+
+ # TODO: Create a client ID for your project.
+ client_id = "YOUR-CLIENT-ID.apps.googleusercontent.com"
+ client_secret = "abc_ThIsIsAsEcReT"
+
+ # TODO: Choose the needed scopes for your applications.
+ scopes = ["https://www.googleapis.com/auth/cloud-platform"]
+
+ credentials = google_auth_oauthlib.get_user_credentials(
+ scopes, client_id, client_secret
+ )
+
+ # 1. Open the link.
+ # 2. Authorize the application to have access to your account.
+ # 3. Copy and paste the authorization code to the prompt.
+
+ # Use the credentials to construct a client for Google APIs.
+ from google.cloud import bigquery
+
+ bigquery_client = bigquery.Client(
+ credentials=credentials, project="your-project-id"
+ )
+ print(list(bigquery_client.query("SELECT 1").result()))
+ """
+
+ client_config = {
+ "installed": {
+ "client_id": client_id,
+ "client_secret": client_secret,
+ "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+ "token_uri": "https://oauth2.googleapis.com/token",
+ }
+ }
+
+ app_flow = google_auth_oauthlib.flow.InstalledAppFlow.from_client_config(
+ client_config, scopes=scopes
+ )
+
+ port = find_open_port(start=minimum_port, stop=maximum_port)
+ if not port:
+ raise ConnectionError("Could not find open port.")
+
+ return app_flow.run_local_server(host=LOCALHOST, port=port)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/tool/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/tool/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/tool/__main__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/tool/__main__.py
new file mode 100644
index 000000000000..db679a1841f3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/google_auth_oauthlib/tool/__main__.py
@@ -0,0 +1,124 @@
+# Copyright (C) 2017 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Command-line tool for obtaining authorization and credentials from a user.
+
+This tool uses the OAuth 2.0 Authorization Code grant as described in
+`section 1.3.1 of RFC6749`_ and implemeted by
+:class:`google_auth_oauthlib.flow.Flow`.
+
+This tool is intended for assist developers in obtaining credentials
+for testing applications where it may not be possible or easy to run a
+complete OAuth 2.0 authorization flow, especially in the case of code
+samples or embedded devices without input / display capabilities.
+
+This is not intended for production use where a combination of
+companion and on-device applications should complete the OAuth 2.0
+authorization flow to get authorization from the users.
+
+.. _section 1.3.1 of RFC6749: https://tools.ietf.org/html/rfc6749#section-1.3.1
+"""
+
+import json
+import os
+import os.path
+
+import click
+
+import google_auth_oauthlib.flow
+
+
+APP_NAME = "google-oauthlib-tool"
+DEFAULT_CREDENTIALS_FILENAME = "credentials.json"
+
+
+@click.command()
+@click.option(
+ "--client-secrets",
+ metavar="",
+ required=True,
+ help="Path to OAuth2 client secret JSON file.",
+)
+@click.option(
+ "--scope",
+ multiple=True,
+ metavar="",
+ required=True,
+ help="API scopes to authorize access for.",
+)
+@click.option(
+ "--save",
+ is_flag=True,
+ metavar="",
+ show_default=True,
+ default=False,
+ help="Save the credentials to file.",
+)
+@click.option(
+ "--credentials",
+ metavar="",
+ show_default=True,
+ default=os.path.join(click.get_app_dir(APP_NAME), DEFAULT_CREDENTIALS_FILENAME),
+ help="Path to store OAuth2 credentials.",
+)
+def main(client_secrets, scope, save, credentials):
+ """Command-line tool for obtaining authorization and credentials from a user.
+
+ This tool uses the OAuth 2.0 Authorization Code grant as described
+ in section 1.3.1 of RFC6749:
+ https://tools.ietf.org/html/rfc6749#section-1.3.1
+
+ This tool is intended for assist developers in obtaining credentials
+ for testing applications or samples.
+
+ This is not intended for production use where a combination of
+ companion and on-device applications should complete the OAuth 2.0
+ authorization flow to get authorization from the users.
+
+ """
+
+ flow = google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file(
+ client_secrets, scopes=scope
+ )
+
+ creds = flow.run_local_server()
+
+ creds_data = {
+ "token": creds.token,
+ "refresh_token": creds.refresh_token,
+ "token_uri": creds.token_uri,
+ "client_id": creds.client_id,
+ "client_secret": creds.client_secret,
+ "scopes": creds.scopes,
+ }
+
+ if save:
+ del creds_data["token"]
+
+ config_path = os.path.dirname(credentials)
+ if config_path and not os.path.isdir(config_path):
+ os.makedirs(config_path)
+
+ with open(credentials, "w") as outfile:
+ json.dump(creds_data, outfile)
+
+ click.echo("credentials saved: %s" % credentials)
+
+ else:
+ click.echo(json.dumps(creds_data))
+
+
+if __name__ == "__main__":
+ # pylint doesn't realize that click has changed the function signature.
+ main() # pylint: disable=no-value-for-parameter
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/setup.cfg b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/setup.cfg
new file mode 100644
index 000000000000..c3a2b39f6528
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/setup.cfg
@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Generated by synthtool. DO NOT EDIT!
+[bdist_wheel]
+universal = 1
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/setup.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/setup.py
new file mode 100644
index 000000000000..f305c06267da
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/auth/setup.py
@@ -0,0 +1,68 @@
+# Copyright 2014 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import io
+
+from setuptools import find_packages
+from setuptools import setup
+
+
+TOOL_DEPENDENCIES = "click>=6.0.0"
+
+DEPENDENCIES = ("google-auth>=2.15.0", "requests-oauthlib>=0.7.0")
+
+
+with io.open("README.rst", "r") as fh:
+ long_description = fh.read()
+
+
+version = "1.0.0"
+
+setup(
+ name="google-auth-oauthlib",
+ version=version,
+ author="Google Cloud Platform",
+ author_email="jonwayne+google-auth@google.com",
+ description="Google Authentication Library",
+ long_description=long_description,
+ url="https://github.com/GoogleCloudPlatform/google-auth-library-python-oauthlib",
+ packages=find_packages(exclude=("tests*",)),
+ install_requires=DEPENDENCIES,
+ extras_require={"tool": TOOL_DEPENDENCIES},
+ entry_points={
+ "console_scripts": [
+ "google-oauthlib-tool" "=google_auth_oauthlib.tool.__main__:main [tool]"
+ ]
+ },
+ python_requires=">=3.6",
+ license="Apache 2.0",
+ keywords="google auth oauth client oauthlib",
+ classifiers=[
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.6",
+ "Programming Language :: Python :: 3.7",
+ "Programming Language :: Python :: 3.8",
+ "Programming Language :: Python :: 3.9",
+ "Programming Language :: Python :: 3.10",
+ "Programming Language :: Python :: 3.11",
+ "Development Status :: 5 - Production/Stable",
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: Apache Software License",
+ "Operating System :: POSIX",
+ "Operating System :: Microsoft :: Windows",
+ "Operating System :: MacOS :: MacOS X",
+ "Operating System :: OS Independent",
+ "Topic :: Internet :: WWW/HTTP",
+ ],
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/CHANGELOG.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/CHANGELOG.md
new file mode 100644
index 000000000000..0d6959a728a2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/CHANGELOG.md
@@ -0,0 +1,381 @@
+# Changelog
+
+[PyPI History][1]
+
+[1]: https://pypi.org/project/google-cloud-texttospeech/#history
+
+## [2.12.3](https://github.com/googleapis/python-texttospeech/compare/v2.12.2...v2.12.3) (2022-10-07)
+
+
+### Bug Fixes
+
+* **deps:** Allow protobuf 3.19.5 ([#338](https://github.com/googleapis/python-texttospeech/issues/338)) ([aa92121](https://github.com/googleapis/python-texttospeech/commit/aa921215c05588b6555b7b41381b30f8b0079d54))
+
+## [2.12.2](https://github.com/googleapis/python-texttospeech/compare/v2.12.1...v2.12.2) (2022-10-03)
+
+
+### Bug Fixes
+
+* **deps:** Require protobuf >= 3.20.2 ([#335](https://github.com/googleapis/python-texttospeech/issues/335)) ([50b394d](https://github.com/googleapis/python-texttospeech/commit/50b394dc5684b2df6cf544ba7bb5296d384ee0f8))
+
+## [2.12.1](https://github.com/googleapis/python-texttospeech/compare/v2.12.0...v2.12.1) (2022-08-11)
+
+
+### Bug Fixes
+
+* **deps:** allow protobuf < 5.0.0 ([#316](https://github.com/googleapis/python-texttospeech/issues/316)) ([ec75f1e](https://github.com/googleapis/python-texttospeech/commit/ec75f1e5382bd527d17fb347a7ecc7cd35f57ab0))
+* **deps:** require proto-plus >= 1.22.0 ([ec75f1e](https://github.com/googleapis/python-texttospeech/commit/ec75f1e5382bd527d17fb347a7ecc7cd35f57ab0))
+
+## [2.12.0](https://github.com/googleapis/python-texttospeech/compare/v2.11.1...v2.12.0) (2022-07-16)
+
+
+### Features
+
+* add audience parameter ([f450551](https://github.com/googleapis/python-texttospeech/commit/f450551482e52c7f5564bf735b705e22255dc5d8))
+
+
+### Bug Fixes
+
+* **deps:** require google-api-core>=1.32.0,>=2.8.0 ([#304](https://github.com/googleapis/python-texttospeech/issues/304)) ([f450551](https://github.com/googleapis/python-texttospeech/commit/f450551482e52c7f5564bf735b705e22255dc5d8))
+* require python 3.7+ ([#306](https://github.com/googleapis/python-texttospeech/issues/306)) ([192277b](https://github.com/googleapis/python-texttospeech/commit/192277b9b62338840b55fe8e24be582a19f390cd))
+
+## [2.11.1](https://github.com/googleapis/python-texttospeech/compare/v2.11.0...v2.11.1) (2022-06-06)
+
+
+### Bug Fixes
+
+* **deps:** require protobuf <4.0.0dev ([#293](https://github.com/googleapis/python-texttospeech/issues/293)) ([e5ab0d6](https://github.com/googleapis/python-texttospeech/commit/e5ab0d6b69e008653b1500742ede3ead3a748f58))
+
+
+### Documentation
+
+* fix changelog header to consistent size ([#294](https://github.com/googleapis/python-texttospeech/issues/294)) ([8a8b65c](https://github.com/googleapis/python-texttospeech/commit/8a8b65c0e4c39a5671e9998848ebb89ea38d301d))
+
+## [2.11.0](https://github.com/googleapis/python-texttospeech/compare/v2.10.2...v2.11.0) (2022-03-10)
+
+
+### Features
+
+* promote CustomVoiceParams to v1 ([#266](https://github.com/googleapis/python-texttospeech/issues/266)) ([f484e7f](https://github.com/googleapis/python-texttospeech/commit/f484e7fe036fe57a4f432bf30c6421a6541ea486))
+
+## [2.10.2](https://github.com/googleapis/python-texttospeech/compare/v2.10.1...v2.10.2) (2022-03-05)
+
+
+### Bug Fixes
+
+* **deps:** require google-api-core>=1.31.5, >=2.3.2 ([#261](https://github.com/googleapis/python-texttospeech/issues/261)) ([f993058](https://github.com/googleapis/python-texttospeech/commit/f993058b1535e8cc0c71877b8dca9beae3dffb1b))
+* **deps:** require proto-plus>=1.15.0 ([f993058](https://github.com/googleapis/python-texttospeech/commit/f993058b1535e8cc0c71877b8dca9beae3dffb1b))
+
+## [2.10.1](https://github.com/googleapis/python-texttospeech/compare/v2.10.0...v2.10.1) (2022-02-26)
+
+
+### Documentation
+
+* add generated snippets ([#249](https://github.com/googleapis/python-texttospeech/issues/249)) ([f918e82](https://github.com/googleapis/python-texttospeech/commit/f918e82df2e0c499356fa1e095b13f7ac2cd3b6b))
+
+## [2.10.0](https://github.com/googleapis/python-texttospeech/compare/v2.9.1...v2.10.0) (2022-02-03)
+
+
+### Features
+
+* add api key support ([#242](https://github.com/googleapis/python-texttospeech/issues/242)) ([3b4f0d0](https://github.com/googleapis/python-texttospeech/commit/3b4f0d0749529b04ed7fedec3c4b06b6d42c12cd))
+
+
+### Bug Fixes
+
+* resolve DuplicateCredentialArgs error when using credentials_file ([4c11b12](https://github.com/googleapis/python-texttospeech/commit/4c11b127ece0009082fe91062f3f36c8f18e8ffc))
+
+
+### Documentation
+
+* update comments for ListVoicesRequest ([#244](https://github.com/googleapis/python-texttospeech/issues/244)) ([bc5b73f](https://github.com/googleapis/python-texttospeech/commit/bc5b73fbc62900f89a01486c6e8d42d459c34fd6))
+
+## [2.9.1](https://www.github.com/googleapis/python-texttospeech/compare/v2.9.0...v2.9.1) (2022-01-08)
+
+
+### Documentation
+
+* Added virtualenv comment for clarity ([#225](https://www.github.com/googleapis/python-texttospeech/issues/225)) ([61a7fce](https://www.github.com/googleapis/python-texttospeech/commit/61a7fcec0611712cdb1692b830db4aaca4d411b0))
+* update comments for ListVoicesRequest ([#229](https://www.github.com/googleapis/python-texttospeech/issues/229)) ([9ea340c](https://www.github.com/googleapis/python-texttospeech/commit/9ea340cee20298630a6a15bed0ed2df9f69b3d13))
+
+## [2.9.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.8.0...v2.9.0) (2021-11-16)
+
+
+### Features
+
+* update v1 proto ([#221](https://www.github.com/googleapis/python-texttospeech/issues/221)) ([e8776d7](https://www.github.com/googleapis/python-texttospeech/commit/e8776d7a482f495ed5ae0e1235609e3e2d3e6067))
+
+## [2.8.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.7.1...v2.8.0) (2021-11-13)
+
+
+### Features
+
+* **v1beta1:** add CustomVoiceParams ([#215](https://www.github.com/googleapis/python-texttospeech/issues/215)) ([6a18d0f](https://www.github.com/googleapis/python-texttospeech/commit/6a18d0f097e992bd4d90eaf5032ce98aa4af004a))
+
+
+### Documentation
+
+* fix docstring formatting ([#218](https://www.github.com/googleapis/python-texttospeech/issues/218)) ([2c57f95](https://www.github.com/googleapis/python-texttospeech/commit/2c57f95a1af747b49dac41628bd43d485a68583e))
+
+## [2.7.1](https://www.github.com/googleapis/python-texttospeech/compare/v2.7.0...v2.7.1) (2021-11-01)
+
+
+### Bug Fixes
+
+* **deps:** drop packaging dependency ([99ac70b](https://www.github.com/googleapis/python-texttospeech/commit/99ac70ba45d7c500d0f19a30dead060c0db4453c))
+* **deps:** require google-api-core >= 1.28.0 ([99ac70b](https://www.github.com/googleapis/python-texttospeech/commit/99ac70ba45d7c500d0f19a30dead060c0db4453c))
+
+
+### Documentation
+
+* list oneofs in docstring ([99ac70b](https://www.github.com/googleapis/python-texttospeech/commit/99ac70ba45d7c500d0f19a30dead060c0db4453c))
+
+## [2.7.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.6.0...v2.7.0) (2021-10-18)
+
+
+### Features
+
+* add support for python 3.10 ([#202](https://www.github.com/googleapis/python-texttospeech/issues/202)) ([2ffa70b](https://www.github.com/googleapis/python-texttospeech/commit/2ffa70b6c35707142d66476b0ef5e3bd8d6d0052))
+
+## [2.6.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.3...v2.6.0) (2021-10-07)
+
+
+### Features
+
+* add context manager support in client ([#196](https://www.github.com/googleapis/python-texttospeech/issues/196)) ([73d9290](https://www.github.com/googleapis/python-texttospeech/commit/73d9290cdea69a00ba317ae017a1d07bcf734989))
+
+## [2.5.3](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.2...v2.5.3) (2021-09-24)
+
+
+### Bug Fixes
+
+* add 'dict' annotation type to 'request' ([e74b994](https://www.github.com/googleapis/python-texttospeech/commit/e74b9942d480bf7e360bc61ff183909873fc20a6))
+
+## [2.5.2](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.1...v2.5.2) (2021-07-28)
+
+
+### Bug Fixes
+
+* enable self signed jwt for grpc ([#171](https://www.github.com/googleapis/python-texttospeech/issues/171)) ([9c1c437](https://www.github.com/googleapis/python-texttospeech/commit/9c1c4371caa712a749b406257c09d98f6b428e7b))
+
+
+### Documentation
+
+* add Samples section to CONTRIBUTING.rst ([#166](https://www.github.com/googleapis/python-texttospeech/issues/166)) ([053abe3](https://www.github.com/googleapis/python-texttospeech/commit/053abe3afc1107bdacd164e6ca4cd60b5ca07df7))
+
+
+### Miscellaneous Chores
+
+* release as 2.5.2 ([#172](https://www.github.com/googleapis/python-texttospeech/issues/172)) ([3804727](https://www.github.com/googleapis/python-texttospeech/commit/3804727995d0357fa0c4c5c246210768e0ce7124))
+
+## [2.5.1](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.0...v2.5.1) (2021-07-20)
+
+
+### Bug Fixes
+
+* **deps:** pin 'google-{api,cloud}-core', 'google-auth' to allow 2.x versions ([#165](https://www.github.com/googleapis/python-texttospeech/issues/165)) ([d78b384](https://www.github.com/googleapis/python-texttospeech/commit/d78b384d302a1976682f35875ce2d4f7b60d7a6c))
+
+## [2.5.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.4.0...v2.5.0) (2021-07-01)
+
+
+### Features
+
+* add always_use_jwt_access ([#155](https://www.github.com/googleapis/python-texttospeech/issues/155)) ([cd10c37](https://www.github.com/googleapis/python-texttospeech/commit/cd10c3704db610f2abf65c9142cfdaa867d8490a))
+
+
+### Bug Fixes
+
+* disable always_use_jwt_access ([#159](https://www.github.com/googleapis/python-texttospeech/issues/159)) ([d109303](https://www.github.com/googleapis/python-texttospeech/commit/d109303898facc663a6e7fe9212440831c1eeb75))
+
+
+### Documentation
+
+* omit mention of Python 2.7 in 'CONTRIBUTING.rst' ([#1127](https://www.github.com/googleapis/python-texttospeech/issues/1127)) ([#150](https://www.github.com/googleapis/python-texttospeech/issues/150)) ([d2954ba](https://www.github.com/googleapis/python-texttospeech/commit/d2954ba91385db6d581f75154fb11c969f6ca0e2)), closes [#1126](https://www.github.com/googleapis/python-texttospeech/issues/1126)
+
+## [2.4.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.3.0...v2.4.0) (2021-05-28)
+
+
+### Features
+
+* support self-signed JWT flow for service accounts ([8a08836](https://www.github.com/googleapis/python-texttospeech/commit/8a08836487c1b7e4e58d3c07a4e26005d40793f0))
+
+
+### Bug Fixes
+
+* add async client to %name_%version/init.py ([8a08836](https://www.github.com/googleapis/python-texttospeech/commit/8a08836487c1b7e4e58d3c07a4e26005d40793f0))
+
+## [2.3.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.2.0...v2.3.0) (2021-03-31)
+
+
+### Features
+
+* add `from_service_account_info` to clients ([139e6e8](https://www.github.com/googleapis/python-texttospeech/commit/139e6e8511cdce4c0be7983520f7efc47092f3b1))
+* Add ALAW support on client library and improve the ListVoiceRequest message's documentation ([#113](https://www.github.com/googleapis/python-texttospeech/issues/113)) ([8bbd380](https://www.github.com/googleapis/python-texttospeech/commit/8bbd38014fe796b30f4b12ae9432d3a05c130063))
+* add common resource helper methods ([139e6e8](https://www.github.com/googleapis/python-texttospeech/commit/139e6e8511cdce4c0be7983520f7efc47092f3b1))
+* support custom client info ([#82](https://www.github.com/googleapis/python-texttospeech/issues/82)) ([0612793](https://www.github.com/googleapis/python-texttospeech/commit/06127932a920f6318db8f25d6430755b35d09bb5))
+
+
+### Bug Fixes
+
+* change default retry and timeout settings ([139e6e8](https://www.github.com/googleapis/python-texttospeech/commit/139e6e8511cdce4c0be7983520f7efc47092f3b1))
+
+
+### Documentation
+
+* use sphinx-1.5.5 for sphinx-docfx-yaml ([#89](https://www.github.com/googleapis/python-texttospeech/issues/89)) ([feb04c5](https://www.github.com/googleapis/python-texttospeech/commit/feb04c50b56c2c3359b92d8b5887c8ee50be2b95))
+
+## [2.2.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.1.0...v2.2.0) (2020-08-10)
+
+
+### Features
+
+* incorporate upstream changes ([#73](https://www.github.com/googleapis/python-texttospeech/issues/73)) ([8ee5447](https://www.github.com/googleapis/python-texttospeech/commit/8ee544740f18497d9925bcf77e5ab96695503589))
+ * support MULAW audio encoding
+ * support MP3_64_KBPS audio encoding
+ * support timepointing via SSML tag
+ * support quota_project_id
+
+## [2.1.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.0.0...v2.1.0) (2020-06-20)
+
+
+### Features
+
+* add async client ([#53](https://www.github.com/googleapis/python-texttospeech/issues/53)) ([887d8d5](https://www.github.com/googleapis/python-texttospeech/commit/887d8d501ce9255fee44170b5fc40ebfb1ea953d))
+
+
+### Documentation
+
+* change relative URLs to absolute URLs to fix broken links ([#40](https://www.github.com/googleapis/python-texttospeech/issues/40)) ([b68df44](https://www.github.com/googleapis/python-texttospeech/commit/b68df446daa7983cad1d31553ece6df569c932b2))
+
+## [2.0.0](https://www.github.com/googleapis/python-texttospeech/compare/v1.0.1...v2.0.0) (2020-06-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* This release has breaking changes. See the [2.0.0 Migration Guide](https://github.com/googleapis/python-texttospeech/blob/main/UPGRADING.md#200-migration-guide) for details.
+
+### Features
+
+* regenerate with microgenerator ([#30](https://www.github.com/googleapis/python-texttospeech/issues/30)) ([3181b55](https://www.github.com/googleapis/python-texttospeech/commit/3181b55733da7aecde37009a0dd77117434deceb))
+
+
+### Bug Fixes
+
+* address PR comments ([65f903b](https://www.github.com/googleapis/python-texttospeech/commit/65f903b00395716fad272ca4fc973755735e1e20))
+
+## [1.0.1](https://www.github.com/googleapis/python-texttospeech/compare/v1.0.0...v1.0.1) (2020-02-28)
+
+
+### Bug Fixes
+
+* update url in setup.py ([#13](https://www.github.com/googleapis/python-texttospeech/issues/13)) ([dc17707](https://www.github.com/googleapis/python-texttospeech/commit/dc17707c41feb885d94f1045ef14e4b9e0898716))
+
+## [1.0.0](https://www.github.com/googleapis/python-texttospeech/compare/v0.5.0...v1.0.0) (2020-02-28)
+
+
+### Features
+
+* bump release status to GA ([#9](https://www.github.com/googleapis/python-texttospeech/issues/9)) ([03a639e](https://www.github.com/googleapis/python-texttospeech/commit/03a639e16256d9211c1fe88991440f2cc22eccd6))
+
+## 0.5.0
+
+07-24-2019 17:48 PDT
+
+
+### Implementation Changes
+- Allow kwargs to be passed to create_channel (via synth). ([#8407](https://github.com/googleapis/google-cloud-python/pull/8407))
+- Reformat protos, update nox session docs (via synth). ([#7941](https://github.com/googleapis/google-cloud-python/pull/7941))
+- Remove classifier for Python 3.4 for end-of-life. ([#7535](https://github.com/googleapis/google-cloud-python/pull/7535))
+
+### New Features
+- Add 'client_options' support (via synth). ([#8525](https://github.com/googleapis/google-cloud-python/pull/8525))
+
+### Dependencies
+- Bump minimum version for google-api-core to 1.14.0. ([#8709](https://github.com/googleapis/google-cloud-python/pull/8709))
+
+### Documentation
+- Link to googleapis.dev documentation in READMEs. ([#8705](https://github.com/googleapis/google-cloud-python/pull/8705))
+- Add compatibility check badges to READMEs. ([#8288](https://github.com/googleapis/google-cloud-python/pull/8288))
+- Repair top-level API reference page. ([#8435](https://github.com/googleapis/google-cloud-python/pull/8435))
+- Updated client library documentation URLs. ([#7307](https://github.com/googleapis/google-cloud-python/pull/7307))
+
+### Internal / Testing Changes
+- Pin black version (via synth). ([#8599](https://github.com/googleapis/google-cloud-python/pull/8599))
+- Add docs job to publish to googleapis.dev. ([#8464](https://github.com/googleapis/google-cloud-python/pull/8464))
+- Declare encoding as utf-8 in pb2 files (via synth). ([#8367](https://github.com/googleapis/google-cloud-python/pull/8367))
+- Add disclaimer to auto-generated template files (via synth). ([#8331](https://github.com/googleapis/google-cloud-python/pull/8331))
+- Blacken (via synth). ([#8281](https://github.com/googleapis/google-cloud-python/pull/8281))
+
+## 0.4.0
+
+02-07-2019 15:21 PST
+
+
+### Implementation Changes
+- Pick up stub docstring fix in GAPIC generator. ([#6984](https://github.com/googleapis/google-cloud-python/pull/6984))
+
+### New Features
+- Protoc updates to include effects_profile_id. ([#7097](https://github.com/googleapis/google-cloud-python/pull/7097))
+
+### Documentation
+- Fix `Client Library Documentation` link ([#7109](https://github.com/googleapis/google-cloud-python/pull/7109))
+
+### Internal / Testing Changes
+- Copy proto files alongside protoc versions.
+- Add protos as an artifact to library ([#7205](https://github.com/googleapis/google-cloud-python/pull/7205))
+- Update copyright headers and docstring quoting
+
+## 0.3.0
+
+12-18-2018 09:54 PST
+
+
+### Implementation Changes
+- Import `iam.policy` from `google.api_core`. ([#6741](https://github.com/googleapis/google-cloud-python/pull/6741))
+- Pick up fixes to GAPIC generator. ([#6510](https://github.com/googleapis/google-cloud-python/pull/6510))
+- Fix `client_info` bug, update docstrings. ([#6423](https://github.com/googleapis/google-cloud-python/pull/6423))
+- Re-generate library using texttospeech/synth.py ([#5981](https://github.com/googleapis/google-cloud-python/pull/5981))
+- Add gRPC Transport layer. ([#5959](https://github.com/googleapis/google-cloud-python/pull/5959))
+
+### Dependencies
+- Bump minimum `api_core` version for all GAPIC libs to 1.4.1. ([#6391](https://github.com/googleapis/google-cloud-python/pull/6391))
+- Avoid broken 'google-common-apis 1.5.4' release. ([#6355](https://github.com/googleapis/google-cloud-python/pull/6355))
+
+### Documentation
+- Document Python 2 deprecation ([#6910](https://github.com/googleapis/google-cloud-python/pull/6910))
+- Docs: normalize use of support level badges ([#6159](https://github.com/googleapis/google-cloud-python/pull/6159))
+- Docs: Replace links to `/stable/` with `/latest/`. ([#5901](https://github.com/googleapis/google-cloud-python/pull/5901))
+- Fix docs links for TTS. ([#5483](https://github.com/googleapis/google-cloud-python/pull/5483))
+
+### Internal / Testing Changes
+- Add synth.metadata. ([#6870](https://github.com/googleapis/google-cloud-python/pull/6870))
+- Update noxfile.
+- blacken all gen'd libs ([#6792](https://github.com/googleapis/google-cloud-python/pull/6792))
+- omit local deps ([#6701](https://github.com/googleapis/google-cloud-python/pull/6701))
+- Run black at end of synth.py ([#6698](https://github.com/googleapis/google-cloud-python/pull/6698))
+- Run Black on Generated libraries ([#6666](https://github.com/googleapis/google-cloud-python/pull/6666))
+- Add templates for flake8, coveragerc, noxfile, and black. ([#6642](https://github.com/googleapis/google-cloud-python/pull/6642))
+- Add 'mock' to unit test dependencies for autogen libs. ([#6402](https://github.com/googleapis/google-cloud-python/pull/6402))
+- Add / fix badges for PyPI / versions. ([#6158](https://github.com/googleapis/google-cloud-python/pull/6158))
+- Use new Nox ([#6175](https://github.com/googleapis/google-cloud-python/pull/6175))
+
+## 0.2.0
+
+### New Features
+
+- Add the text-to-speech v1 API surface. (#5468)
+- Re-generate the text-to-speech v1beta1 API surface. (#5468)
+
+### Documentation
+
+- Rename releases to changelog and include from CHANGELOG.md (#5191)
+
+### Internal / Testing Changes
+
+- Add Test runs for Python 3.7 and remove 3.4 (#5295)
+
+## 0.1.0
+
+### Interface additions
+
+- Added text-to-speech v1beta1. (#5049)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/README.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/README.rst
new file mode 100644
index 000000000000..8d2e41bf68c2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/README.rst
@@ -0,0 +1,107 @@
+Python Client for Google Cloud Text-to-Speech API
+=================================================
+
+|stable| |pypi| |versions|
+
+`Google Cloud Text-to-Speech API`_: enables easy integration of Google text recognition technologies into developer applications. Send text and receive synthesized audio output from the Cloud Text-to-Speech API service.
+
+- `Client Library Documentation`_
+- `Product Documentation`_
+
+.. |stable| image:: https://img.shields.io/badge/support-stable-gold.svg
+ :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels
+.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-texttospeech.svg
+ :target: https://pypi.org/project/google-cloud-texttospeech/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-texttospeech.svg
+ :target: https://pypi.org/project/google-cloud-texttospeech/
+.. _Google Cloud Text-to-Speech API: https://cloud.google.com/text-to-speech
+.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/texttospeech/latest
+.. _Product Documentation: https://cloud.google.com/text-to-speech
+
+Quick Start
+-----------
+
+In order to use this library, you first need to go through the following steps:
+
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Google Cloud Text-to-Speech API.`_
+4. `Setup Authentication.`_
+
+.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
+.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
+.. _Enable the Google Cloud Text-to-Speech API.: https://cloud.google.com/text-to-speech
+.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
+
+Installation
+~~~~~~~~~~~~
+
+Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
+create isolated Python environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
+
+With `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
+
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
+
+
+Code samples and snippets
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Code samples and snippets live in the `samples/` folder.
+
+
+Supported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Our client libraries are compatible with all current `active`_ and `maintenance`_ versions of
+Python.
+
+Python >= 3.7
+
+.. _active: https://devguide.python.org/devcycle/#in-development-main-branch
+.. _maintenance: https://devguide.python.org/devcycle/#maintenance-branches
+
+Unsupported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Python <= 3.6
+
+If you are using an `end-of-life`_
+version of Python, we recommend that you update as soon as possible to an actively supported version.
+
+.. _end-of-life: https://devguide.python.org/devcycle/#end-of-life-branches
+
+Mac/Linux
+^^^^^^^^^
+
+.. code-block:: console
+
+ pip install virtualenv
+ virtualenv
+ source /bin/activate
+ /bin/pip install google-cloud-texttospeech
+
+
+Windows
+^^^^^^^
+
+.. code-block:: console
+
+ pip install virtualenv
+ virtualenv
+ \Scripts\activate
+ \Scripts\pip.exe install google-cloud-texttospeech
+
+Next Steps
+~~~~~~~~~~
+
+- Read the `Client Library Documentation`_ for Google Cloud Text-to-Speech API
+ to see other available methods on the client.
+- Read the `Google Cloud Text-to-Speech API Product documentation`_ to learn
+ more about the product and see How-to Guides.
+- View this `README`_ to see the full list of Cloud
+ APIs that we cover.
+
+.. _Google Cloud Text-to-Speech API Product documentation: https://cloud.google.com/text-to-speech
+.. _README: https://github.com/googleapis/google-cloud-python/blob/main/README.rst
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/UPGRADING.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/UPGRADING.md
new file mode 100644
index 000000000000..f1450b1f23f2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/UPGRADING.md
@@ -0,0 +1,151 @@
+# 2.0.0 Migration Guide
+
+The 2.0 release of the `google-cloud-texttospeech` client is a significant upgrade based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), and includes substantial interface changes. Existing code written for earlier versions of this library will likely require updates to use this version. This document describes the changes that have been made, and what you need to do to update your usage.
+
+If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-texttospeech/issues).
+
+## Supported Python Versions
+
+> **WARNING**: Breaking change
+
+The 2.0.0 release requires Python 3.6+.
+
+
+## Method Calls
+
+> **WARNING**: Breaking change
+
+Methods expect request objects. We provide a script that will convert most common use cases.
+
+* Install the library and `libcst`.
+
+```py
+python3 -m pip install google-cloud-texttospeech libcst
+```
+
+* The script `fixup_keywords.py` is shipped with the library. It expects
+an input directory (with the code to convert) and an empty destination directory.
+
+```sh
+$ fixup_keywords.py --input-directory .samples/ --output-directory samples/
+```
+
+**Before:**
+```py
+from google.cloud import texttospeech
+
+client = texttospeech.TextToSpeechClient()
+
+voices = client.list_voices(language_code="no")
+```
+
+
+**After:**
+```py
+from google.cloud import texttospeech
+
+client = texttospeech.TextToSpeechClient()
+
+voices = client.list_voices(request={"language_code": "no"})
+```
+
+### More Details
+
+In `google-cloud-texttospeech<2.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters.
+
+**Before:**
+```py
+ def synthesize_speech(
+ self,
+ input_,
+ voice,
+ audio_config,
+ retry=google.api_core.gapic_v1.method.DEFAULT,
+ timeout=google.api_core.gapic_v1.method.DEFAULT,
+ metadata=None,
+ ):
+```
+
+In the 2.0.0 release, all methods have a single positional parameter `request`. Method docstrings indicate whether a parameter is required or optional.
+
+Some methods have additional keyword only parameters. The available parameters depend on the [`google.api.method_signature` annotation](https://github.com/googleapis/googleapis/blob/master/google/cloud/texttospeech/v1/cloud_tts.proto#L53) specified by the API producer.
+
+
+**After:**
+```py
+ def synthesize_speech(
+ self,
+ request: cloud_tts.SynthesizeSpeechRequest = None,
+ *,
+ input: cloud_tts.SynthesisInput = None,
+ voice: cloud_tts.VoiceSelectionParams = None,
+ audio_config: cloud_tts.AudioConfig = None,
+ retry: retries.Retry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.SynthesizeSpeechResponse:
+```
+
+> **NOTE:** The `request` parameter and flattened keyword parameters for the API are mutually exclusive.
+> Passing both will result in an error.
+
+
+Both of these calls are valid:
+
+```py
+response = client.synthesize_speech(
+ request={
+ "input": input_text,
+ "voice": voice,
+ "audio_config": audio_config
+ }
+)
+```
+
+```py
+response = client.synthesize_speech(
+ input=input_text,
+ voice=voice,
+ audio_config=audio_config
+)
+```
+
+This call is invalid because it mixes `request` with a keyword argument `audio_config`. Executing this code
+will result in an error.
+
+```py
+response = client.synthesize_speech(
+ request={
+ "input": input_text,
+ "voice": voice,
+ },
+ audio_config=audio_config
+)
+```
+
+
+
+## Enums and Types
+
+
+> **WARNING**: Breaking change
+
+The submodules `enums` and `types` have been removed.
+
+**Before:**
+```py
+
+from google.cloud import texttospeech
+
+encoding = texttospeech.enums.AudioEncoding.MP3
+voice = texttospeech.types.VoiceSelectionParams(language_code="en-US")
+```
+
+
+**After:**
+```py
+from google.cloud import texttospeech
+
+encoding = texttospeech.AudioEncoding.MP3
+voice = texttospeech.VoiceSelectionParams(language_code="en-US")
+```
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/README.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/README.rst
new file mode 120000
index 000000000000..89a0106941ff
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/README.rst
@@ -0,0 +1 @@
+../README.rst
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/UPGRADING.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/UPGRADING.md
new file mode 120000
index 000000000000..01097c8c0fb8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/UPGRADING.md
@@ -0,0 +1 @@
+../UPGRADING.md
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/_static/custom.css b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/_static/custom.css
new file mode 100644
index 000000000000..b0a295464b23
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/_static/custom.css
@@ -0,0 +1,20 @@
+div#python2-eol {
+ border-color: red;
+ border-width: medium;
+}
+
+/* Ensure minimum width for 'Parameters' / 'Returns' column */
+dl.field-list > dt {
+ min-width: 100px
+}
+
+/* Insert space between methods for readability */
+dl.method {
+ padding-top: 10px;
+ padding-bottom: 10px
+}
+
+/* Insert empty space between classes */
+dl.class {
+ padding-bottom: 50px
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/_templates/layout.html b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/_templates/layout.html
new file mode 100644
index 000000000000..6316a537f72b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/docs/_templates/layout.html
@@ -0,0 +1,50 @@
+
+{% extends "!layout.html" %}
+{%- block content %}
+{%- if theme_fixed_sidebar|lower == 'true' %}
+
+ {{ sidebar() }}
+ {%- block document %}
+
+ {%- if render_sidebar %}
+
+ {%- endif %}
+
+ {%- block relbar_top %}
+ {%- if theme_show_relbar_top|tobool %}
+
+
+ {{- rellink_markup () }}
+
+ {%- endif %}
+ {% endblock %}
+
+
+
+ As of January 1, 2020 this library no longer supports Python 2 on the latest released version.
+ Library versions released prior to that date will continue to be available. For more information please
+ visit
Python 2 support on Google Cloud .
+
+ {% block body %} {% endblock %}
+
+
+ {%- block relbar_bottom %}
+ {%- if theme_show_relbar_bottom|tobool %}
+
+
+ {{- rellink_markup () }}
+
+ {%- endif %}
+ {% endblock %}
+
+ {%- if render_sidebar %}
+
+ {%- endif %}
+
+ {%- endblock %}
+
+
v documentation".
+# html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a `__
+ language tag. If not specified, the API will return all
+ supported voices. If specified, the ListVoices call will
+ only return voices that can be used to synthesize this
+ language_code. For example, if you specify ``"en-NZ"``,
+ all ``"en-NZ"`` voices will be returned. If you specify
+ ``"no"``, both ``"no-\*"`` (Norwegian) and ``"nb-\*"``
+ (Norwegian Bokmal) voices will be returned.
+
+ This corresponds to the ``language_code`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1.types.ListVoicesResponse:
+ The message returned to the client by the ListVoices
+ method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([language_code])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = cloud_tts.ListVoicesRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if language_code is not None:
+ request.language_code = language_code
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_voices,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def synthesize_speech(
+ self,
+ request: Union[cloud_tts.SynthesizeSpeechRequest, dict] = None,
+ *,
+ input: cloud_tts.SynthesisInput = None,
+ voice: cloud_tts.VoiceSelectionParams = None,
+ audio_config: cloud_tts.AudioConfig = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.SynthesizeSpeechResponse:
+ r"""Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google.cloud import texttospeech_v1
+
+ async def sample_synthesize_speech():
+ # Create a client
+ client = texttospeech_v1.TextToSpeechAsyncClient()
+
+ # Initialize request argument(s)
+ input = texttospeech_v1.SynthesisInput()
+ input.text = "text_value"
+
+ voice = texttospeech_v1.VoiceSelectionParams()
+ voice.language_code = "language_code_value"
+
+ audio_config = texttospeech_v1.AudioConfig()
+ audio_config.audio_encoding = "ALAW"
+
+ request = texttospeech_v1.SynthesizeSpeechRequest(
+ input=input,
+ voice=voice,
+ audio_config=audio_config,
+ )
+
+ # Make the request
+ response = await client.synthesize_speech(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest, dict]):
+ The request object. The top-level message sent by the
+ client for the `SynthesizeSpeech` method.
+ input (:class:`google.cloud.texttospeech_v1.types.SynthesisInput`):
+ Required. The Synthesizer requires
+ either plain text or SSML as input.
+
+ This corresponds to the ``input`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ voice (:class:`google.cloud.texttospeech_v1.types.VoiceSelectionParams`):
+ Required. The desired voice of the
+ synthesized audio.
+
+ This corresponds to the ``voice`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ audio_config (:class:`google.cloud.texttospeech_v1.types.AudioConfig`):
+ Required. The configuration of the
+ synthesized audio.
+
+ This corresponds to the ``audio_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse:
+ The message returned to the client by the
+ SynthesizeSpeech method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([input, voice, audio_config])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = cloud_tts.SynthesizeSpeechRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if input is not None:
+ request.input = input
+ if voice is not None:
+ request.voice = voice
+ if audio_config is not None:
+ request.audio_config = audio_config
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.synthesize_speech,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb):
+ await self.transport.close()
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ gapic_version=pkg_resources.get_distribution(
+ "google-cloud-texttospeech",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("TextToSpeechAsyncClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
new file mode 100644
index 000000000000..4ad59c0b6413
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
@@ -0,0 +1,682 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import os
+import re
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
+
+from google.api_core import client_options as client_options_lib
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.exceptions import MutualTLSChannelError # type: ignore
+from google.auth.transport import mtls # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+import pkg_resources
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.cloud.texttospeech_v1.types import cloud_tts
+
+from .transports.base import DEFAULT_CLIENT_INFO, TextToSpeechTransport
+from .transports.grpc import TextToSpeechGrpcTransport
+from .transports.grpc_asyncio import TextToSpeechGrpcAsyncIOTransport
+
+
+class TextToSpeechClientMeta(type):
+ """Metaclass for the TextToSpeech client.
+
+ This provides class-level methods for building and retrieving
+ support objects (e.g. transport) without polluting the client instance
+ objects.
+ """
+
+ _transport_registry = OrderedDict() # type: Dict[str, Type[TextToSpeechTransport]]
+ _transport_registry["grpc"] = TextToSpeechGrpcTransport
+ _transport_registry["grpc_asyncio"] = TextToSpeechGrpcAsyncIOTransport
+
+ def get_transport_class(
+ cls,
+ label: str = None,
+ ) -> Type[TextToSpeechTransport]:
+ """Returns an appropriate transport class.
+
+ Args:
+ label: The name of the desired transport. If none is
+ provided, then the first transport in the registry is used.
+
+ Returns:
+ The transport class to use.
+ """
+ # If a specific transport is requested, return that one.
+ if label:
+ return cls._transport_registry[label]
+
+ # No transport is requested; return the default (that is, the first one
+ # in the dictionary).
+ return next(iter(cls._transport_registry.values()))
+
+
+class TextToSpeechClient(metaclass=TextToSpeechClientMeta):
+ """Service that implements Google Cloud Text-to-Speech API."""
+
+ @staticmethod
+ def _get_default_mtls_endpoint(api_endpoint):
+ """Converts api endpoint to mTLS endpoint.
+
+ Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
+ "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
+ Args:
+ api_endpoint (Optional[str]): the api endpoint to convert.
+ Returns:
+ str: converted mTLS api endpoint.
+ """
+ if not api_endpoint:
+ return api_endpoint
+
+ mtls_endpoint_re = re.compile(
+ r"(?P[^.]+)(?P\.mtls)?(?P\.sandbox)?(?P\.googleapis\.com)?"
+ )
+
+ m = mtls_endpoint_re.match(api_endpoint)
+ name, mtls, sandbox, googledomain = m.groups()
+ if mtls or not googledomain:
+ return api_endpoint
+
+ if sandbox:
+ return api_endpoint.replace(
+ "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
+ )
+
+ return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
+
+ DEFAULT_ENDPOINT = "texttospeech.googleapis.com"
+ DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore
+ DEFAULT_ENDPOINT
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ TextToSpeechClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_info(info)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ TextToSpeechClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_file(filename)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ from_service_account_json = from_service_account_file
+
+ @property
+ def transport(self) -> TextToSpeechTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ TextToSpeechTransport: The transport used by the client
+ instance.
+ """
+ return self._transport
+
+ @staticmethod
+ def model_path(
+ project: str,
+ location: str,
+ model: str,
+ ) -> str:
+ """Returns a fully-qualified model string."""
+ return "projects/{project}/locations/{location}/models/{model}".format(
+ project=project,
+ location=location,
+ model=model,
+ )
+
+ @staticmethod
+ def parse_model_path(path: str) -> Dict[str, str]:
+ """Parses a model path into its component segments."""
+ m = re.match(
+ r"^projects/(?P.+?)/locations/(?P.+?)/models/(?P.+?)$",
+ path,
+ )
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_billing_account_path(
+ billing_account: str,
+ ) -> str:
+ """Returns a fully-qualified billing_account string."""
+ return "billingAccounts/{billing_account}".format(
+ billing_account=billing_account,
+ )
+
+ @staticmethod
+ def parse_common_billing_account_path(path: str) -> Dict[str, str]:
+ """Parse a billing_account path into its component segments."""
+ m = re.match(r"^billingAccounts/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_folder_path(
+ folder: str,
+ ) -> str:
+ """Returns a fully-qualified folder string."""
+ return "folders/{folder}".format(
+ folder=folder,
+ )
+
+ @staticmethod
+ def parse_common_folder_path(path: str) -> Dict[str, str]:
+ """Parse a folder path into its component segments."""
+ m = re.match(r"^folders/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_organization_path(
+ organization: str,
+ ) -> str:
+ """Returns a fully-qualified organization string."""
+ return "organizations/{organization}".format(
+ organization=organization,
+ )
+
+ @staticmethod
+ def parse_common_organization_path(path: str) -> Dict[str, str]:
+ """Parse a organization path into its component segments."""
+ m = re.match(r"^organizations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_project_path(
+ project: str,
+ ) -> str:
+ """Returns a fully-qualified project string."""
+ return "projects/{project}".format(
+ project=project,
+ )
+
+ @staticmethod
+ def parse_common_project_path(path: str) -> Dict[str, str]:
+ """Parse a project path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_location_path(
+ project: str,
+ location: str,
+ ) -> str:
+ """Returns a fully-qualified location string."""
+ return "projects/{project}/locations/{location}".format(
+ project=project,
+ location=location,
+ )
+
+ @staticmethod
+ def parse_common_location_path(path: str) -> Dict[str, str]:
+ """Parse a location path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/locations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[client_options_lib.ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+ use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
+ use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
+ if use_client_cert not in ("true", "false"):
+ raise ValueError(
+ "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"
+ )
+ if use_mtls_endpoint not in ("auto", "never", "always"):
+ raise MutualTLSChannelError(
+ "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"
+ )
+
+ # Figure out the client cert source to use.
+ client_cert_source = None
+ if use_client_cert == "true":
+ if client_options.client_cert_source:
+ client_cert_source = client_options.client_cert_source
+ elif mtls.has_default_client_cert_source():
+ client_cert_source = mtls.default_client_cert_source()
+
+ # Figure out which api endpoint to use.
+ if client_options.api_endpoint is not None:
+ api_endpoint = client_options.api_endpoint
+ elif use_mtls_endpoint == "always" or (
+ use_mtls_endpoint == "auto" and client_cert_source
+ ):
+ api_endpoint = cls.DEFAULT_MTLS_ENDPOINT
+ else:
+ api_endpoint = cls.DEFAULT_ENDPOINT
+
+ return api_endpoint, client_cert_source
+
+ def __init__(
+ self,
+ *,
+ credentials: Optional[ga_credentials.Credentials] = None,
+ transport: Union[str, TextToSpeechTransport, None] = None,
+ client_options: Optional[client_options_lib.ClientOptions] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the text to speech client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, TextToSpeechTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. It won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ if isinstance(client_options, dict):
+ client_options = client_options_lib.from_dict(client_options)
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+
+ api_endpoint, client_cert_source_func = self.get_mtls_endpoint_and_cert_source(
+ client_options
+ )
+
+ api_key_value = getattr(client_options, "api_key", None)
+ if api_key_value and credentials:
+ raise ValueError(
+ "client_options.api_key and credentials are mutually exclusive"
+ )
+
+ # Save or instantiate the transport.
+ # Ordinarily, we provide the transport, but allowing a custom transport
+ # instance provides an extensibility point for unusual situations.
+ if isinstance(transport, TextToSpeechTransport):
+ # transport is a TextToSpeechTransport instance.
+ if credentials or client_options.credentials_file or api_key_value:
+ raise ValueError(
+ "When providing a transport instance, "
+ "provide its credentials directly."
+ )
+ if client_options.scopes:
+ raise ValueError(
+ "When providing a transport instance, provide its scopes "
+ "directly."
+ )
+ self._transport = transport
+ else:
+ import google.auth._default # type: ignore
+
+ if api_key_value and hasattr(
+ google.auth._default, "get_api_key_credentials"
+ ):
+ credentials = google.auth._default.get_api_key_credentials(
+ api_key_value
+ )
+
+ Transport = type(self).get_transport_class(transport)
+ self._transport = Transport(
+ credentials=credentials,
+ credentials_file=client_options.credentials_file,
+ host=api_endpoint,
+ scopes=client_options.scopes,
+ client_cert_source_for_mtls=client_cert_source_func,
+ quota_project_id=client_options.quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=True,
+ api_audience=client_options.api_audience,
+ )
+
+ def list_voices(
+ self,
+ request: Union[cloud_tts.ListVoicesRequest, dict] = None,
+ *,
+ language_code: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.ListVoicesResponse:
+ r"""Returns a list of Voice supported for synthesis.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google.cloud import texttospeech_v1
+
+ def sample_list_voices():
+ # Create a client
+ client = texttospeech_v1.TextToSpeechClient()
+
+ # Initialize request argument(s)
+ request = texttospeech_v1.ListVoicesRequest(
+ )
+
+ # Make the request
+ response = client.list_voices(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.cloud.texttospeech_v1.types.ListVoicesRequest, dict]):
+ The request object. The top-level message sent by the
+ client for the `ListVoices` method.
+ language_code (str):
+ Optional. Recommended.
+ `BCP-47 `__
+ language tag. If not specified, the API will return all
+ supported voices. If specified, the ListVoices call will
+ only return voices that can be used to synthesize this
+ language_code. For example, if you specify ``"en-NZ"``,
+ all ``"en-NZ"`` voices will be returned. If you specify
+ ``"no"``, both ``"no-\*"`` (Norwegian) and ``"nb-\*"``
+ (Norwegian Bokmal) voices will be returned.
+
+ This corresponds to the ``language_code`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1.types.ListVoicesResponse:
+ The message returned to the client by the ListVoices
+ method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([language_code])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a cloud_tts.ListVoicesRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, cloud_tts.ListVoicesRequest):
+ request = cloud_tts.ListVoicesRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if language_code is not None:
+ request.language_code = language_code
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_voices]
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def synthesize_speech(
+ self,
+ request: Union[cloud_tts.SynthesizeSpeechRequest, dict] = None,
+ *,
+ input: cloud_tts.SynthesisInput = None,
+ voice: cloud_tts.VoiceSelectionParams = None,
+ audio_config: cloud_tts.AudioConfig = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.SynthesizeSpeechResponse:
+ r"""Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google.cloud import texttospeech_v1
+
+ def sample_synthesize_speech():
+ # Create a client
+ client = texttospeech_v1.TextToSpeechClient()
+
+ # Initialize request argument(s)
+ input = texttospeech_v1.SynthesisInput()
+ input.text = "text_value"
+
+ voice = texttospeech_v1.VoiceSelectionParams()
+ voice.language_code = "language_code_value"
+
+ audio_config = texttospeech_v1.AudioConfig()
+ audio_config.audio_encoding = "ALAW"
+
+ request = texttospeech_v1.SynthesizeSpeechRequest(
+ input=input,
+ voice=voice,
+ audio_config=audio_config,
+ )
+
+ # Make the request
+ response = client.synthesize_speech(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest, dict]):
+ The request object. The top-level message sent by the
+ client for the `SynthesizeSpeech` method.
+ input (google.cloud.texttospeech_v1.types.SynthesisInput):
+ Required. The Synthesizer requires
+ either plain text or SSML as input.
+
+ This corresponds to the ``input`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ voice (google.cloud.texttospeech_v1.types.VoiceSelectionParams):
+ Required. The desired voice of the
+ synthesized audio.
+
+ This corresponds to the ``voice`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ audio_config (google.cloud.texttospeech_v1.types.AudioConfig):
+ Required. The configuration of the
+ synthesized audio.
+
+ This corresponds to the ``audio_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse:
+ The message returned to the client by the
+ SynthesizeSpeech method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([input, voice, audio_config])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a cloud_tts.SynthesizeSpeechRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, cloud_tts.SynthesizeSpeechRequest):
+ request = cloud_tts.SynthesizeSpeechRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if input is not None:
+ request.input = input
+ if voice is not None:
+ request.voice = voice
+ if audio_config is not None:
+ request.audio_config = audio_config
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.synthesize_speech]
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, type, value, traceback):
+ """Releases underlying transport's resources.
+
+ .. warning::
+ ONLY use as a context manager if the transport is NOT shared
+ with other clients! Exiting the with block will CLOSE the transport
+ and may cause errors in other clients!
+ """
+ self.transport.close()
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ gapic_version=pkg_resources.get_distribution(
+ "google-cloud-texttospeech",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("TextToSpeechClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/__init__.py
new file mode 100644
index 000000000000..9a13500994d8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/__init__.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+from typing import Dict, Type
+
+from .base import TextToSpeechTransport
+from .grpc import TextToSpeechGrpcTransport
+from .grpc_asyncio import TextToSpeechGrpcAsyncIOTransport
+
+# Compile a registry of transports.
+_transport_registry = OrderedDict() # type: Dict[str, Type[TextToSpeechTransport]]
+_transport_registry["grpc"] = TextToSpeechGrpcTransport
+_transport_registry["grpc_asyncio"] = TextToSpeechGrpcAsyncIOTransport
+
+__all__ = (
+ "TextToSpeechTransport",
+ "TextToSpeechGrpcTransport",
+ "TextToSpeechGrpcAsyncIOTransport",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/base.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/base.py
new file mode 100644
index 000000000000..93ee86f7b929
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/base.py
@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import abc
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Union
+
+import google.api_core
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+import google.auth # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+import pkg_resources
+
+from google.cloud.texttospeech_v1.types import cloud_tts
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ gapic_version=pkg_resources.get_distribution(
+ "google-cloud-texttospeech",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+class TextToSpeechTransport(abc.ABC):
+ """Abstract transport class for TextToSpeech."""
+
+ AUTH_SCOPES = ("https://www.googleapis.com/auth/cloud-platform",)
+
+ DEFAULT_HOST: str = "texttospeech.googleapis.com"
+
+ def __init__(
+ self,
+ *,
+ host: str = DEFAULT_HOST,
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ **kwargs,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A list of scopes.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+ """
+
+ scopes_kwargs = {"scopes": scopes, "default_scopes": self.AUTH_SCOPES}
+
+ # Save the scopes.
+ self._scopes = scopes
+
+ # If no credentials are provided, then determine the appropriate
+ # defaults.
+ if credentials and credentials_file:
+ raise core_exceptions.DuplicateCredentialArgs(
+ "'credentials_file' and 'credentials' are mutually exclusive"
+ )
+
+ if credentials_file is not None:
+ credentials, _ = google.auth.load_credentials_from_file(
+ credentials_file, **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ elif credentials is None:
+ credentials, _ = google.auth.default(
+ **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ # Don't apply audience if the credentials file passed from user.
+ if hasattr(credentials, "with_gdch_audience"):
+ credentials = credentials.with_gdch_audience(
+ api_audience if api_audience else host
+ )
+
+ # If the credentials are service account credentials, then always try to use self signed JWT.
+ if (
+ always_use_jwt_access
+ and isinstance(credentials, service_account.Credentials)
+ and hasattr(service_account.Credentials, "with_always_use_jwt_access")
+ ):
+ credentials = credentials.with_always_use_jwt_access(True)
+
+ # Save the credentials.
+ self._credentials = credentials
+
+ # Save the hostname. Default to port 443 (HTTPS) if none is specified.
+ if ":" not in host:
+ host += ":443"
+ self._host = host
+
+ def _prep_wrapped_messages(self, client_info):
+ # Precompute the wrapped methods.
+ self._wrapped_methods = {
+ self.list_voices: gapic_v1.method.wrap_method(
+ self.list_voices,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ self.synthesize_speech: gapic_v1.method.wrap_method(
+ self.synthesize_speech,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ }
+
+ def close(self):
+ """Closes resources associated with the transport.
+
+ .. warning::
+ Only call this method if the transport is NOT shared
+ with other clients - this may cause errors in other clients!
+ """
+ raise NotImplementedError()
+
+ @property
+ def list_voices(
+ self,
+ ) -> Callable[
+ [cloud_tts.ListVoicesRequest],
+ Union[cloud_tts.ListVoicesResponse, Awaitable[cloud_tts.ListVoicesResponse]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def synthesize_speech(
+ self,
+ ) -> Callable[
+ [cloud_tts.SynthesizeSpeechRequest],
+ Union[
+ cloud_tts.SynthesizeSpeechResponse,
+ Awaitable[cloud_tts.SynthesizeSpeechResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def kind(self) -> str:
+ raise NotImplementedError()
+
+
+__all__ = ("TextToSpeechTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/grpc.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/grpc.py
new file mode 100644
index 000000000000..a6edeb474967
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/grpc.py
@@ -0,0 +1,294 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import Callable, Dict, Optional, Sequence, Tuple, Union
+import warnings
+
+from google.api_core import gapic_v1, grpc_helpers
+import google.auth # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+import grpc # type: ignore
+
+from google.cloud.texttospeech_v1.types import cloud_tts
+
+from .base import DEFAULT_CLIENT_INFO, TextToSpeechTransport
+
+
+class TextToSpeechGrpcTransport(TextToSpeechTransport):
+ """gRPC backend transport for TextToSpeech.
+
+ Service that implements Google Cloud Text-to-Speech API.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _stubs: Dict[str, Callable]
+
+ def __init__(
+ self,
+ *,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Sequence[str] = None,
+ channel: grpc.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional(Sequence[str])): A list of scopes. This argument is
+ ignored if ``channel`` is provided.
+ channel (Optional[grpc.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> grpc.Channel:
+ """Create and return a gRPC channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ grpc.Channel: A gRPC channel object.
+
+ Raises:
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+
+ return grpc_helpers.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ @property
+ def grpc_channel(self) -> grpc.Channel:
+ """Return the channel designed to connect to this service."""
+ return self._grpc_channel
+
+ @property
+ def list_voices(
+ self,
+ ) -> Callable[[cloud_tts.ListVoicesRequest], cloud_tts.ListVoicesResponse]:
+ r"""Return a callable for the list voices method over gRPC.
+
+ Returns a list of Voice supported for synthesis.
+
+ Returns:
+ Callable[[~.ListVoicesRequest],
+ ~.ListVoicesResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_voices" not in self._stubs:
+ self._stubs["list_voices"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1.TextToSpeech/ListVoices",
+ request_serializer=cloud_tts.ListVoicesRequest.serialize,
+ response_deserializer=cloud_tts.ListVoicesResponse.deserialize,
+ )
+ return self._stubs["list_voices"]
+
+ @property
+ def synthesize_speech(
+ self,
+ ) -> Callable[
+ [cloud_tts.SynthesizeSpeechRequest], cloud_tts.SynthesizeSpeechResponse
+ ]:
+ r"""Return a callable for the synthesize speech method over gRPC.
+
+ Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ Returns:
+ Callable[[~.SynthesizeSpeechRequest],
+ ~.SynthesizeSpeechResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "synthesize_speech" not in self._stubs:
+ self._stubs["synthesize_speech"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1.TextToSpeech/SynthesizeSpeech",
+ request_serializer=cloud_tts.SynthesizeSpeechRequest.serialize,
+ response_deserializer=cloud_tts.SynthesizeSpeechResponse.deserialize,
+ )
+ return self._stubs["synthesize_speech"]
+
+ def close(self):
+ self.grpc_channel.close()
+
+ @property
+ def kind(self) -> str:
+ return "grpc"
+
+
+__all__ = ("TextToSpeechGrpcTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/grpc_asyncio.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/grpc_asyncio.py
new file mode 100644
index 000000000000..e7d304cd44f5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/transports/grpc_asyncio.py
@@ -0,0 +1,296 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Tuple, Union
+import warnings
+
+from google.api_core import gapic_v1, grpc_helpers_async
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+import grpc # type: ignore
+from grpc.experimental import aio # type: ignore
+
+from google.cloud.texttospeech_v1.types import cloud_tts
+
+from .base import DEFAULT_CLIENT_INFO, TextToSpeechTransport
+from .grpc import TextToSpeechGrpcTransport
+
+
+class TextToSpeechGrpcAsyncIOTransport(TextToSpeechTransport):
+ """gRPC AsyncIO backend transport for TextToSpeech.
+
+ Service that implements Google Cloud Text-to-Speech API.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _grpc_channel: aio.Channel
+ _stubs: Dict[str, Callable] = {}
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> aio.Channel:
+ """Create and return a gRPC AsyncIO channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ aio.Channel: A gRPC AsyncIO channel object.
+ """
+
+ return grpc_helpers_async.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ def __init__(
+ self,
+ *,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ channel: aio.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id=None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ channel (Optional[aio.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @property
+ def grpc_channel(self) -> aio.Channel:
+ """Create the channel designed to connect to this service.
+
+ This property caches on the instance; repeated calls return
+ the same channel.
+ """
+ # Return the channel from cache.
+ return self._grpc_channel
+
+ @property
+ def list_voices(
+ self,
+ ) -> Callable[
+ [cloud_tts.ListVoicesRequest], Awaitable[cloud_tts.ListVoicesResponse]
+ ]:
+ r"""Return a callable for the list voices method over gRPC.
+
+ Returns a list of Voice supported for synthesis.
+
+ Returns:
+ Callable[[~.ListVoicesRequest],
+ Awaitable[~.ListVoicesResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_voices" not in self._stubs:
+ self._stubs["list_voices"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1.TextToSpeech/ListVoices",
+ request_serializer=cloud_tts.ListVoicesRequest.serialize,
+ response_deserializer=cloud_tts.ListVoicesResponse.deserialize,
+ )
+ return self._stubs["list_voices"]
+
+ @property
+ def synthesize_speech(
+ self,
+ ) -> Callable[
+ [cloud_tts.SynthesizeSpeechRequest],
+ Awaitable[cloud_tts.SynthesizeSpeechResponse],
+ ]:
+ r"""Return a callable for the synthesize speech method over gRPC.
+
+ Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ Returns:
+ Callable[[~.SynthesizeSpeechRequest],
+ Awaitable[~.SynthesizeSpeechResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "synthesize_speech" not in self._stubs:
+ self._stubs["synthesize_speech"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1.TextToSpeech/SynthesizeSpeech",
+ request_serializer=cloud_tts.SynthesizeSpeechRequest.serialize,
+ response_deserializer=cloud_tts.SynthesizeSpeechResponse.deserialize,
+ )
+ return self._stubs["synthesize_speech"]
+
+ def close(self):
+ return self.grpc_channel.close()
+
+
+__all__ = ("TextToSpeechGrpcAsyncIOTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/__init__.py
new file mode 100644
index 000000000000..f7225093bd64
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/__init__.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from .cloud_tts import (
+ AudioConfig,
+ AudioEncoding,
+ CustomVoiceParams,
+ ListVoicesRequest,
+ ListVoicesResponse,
+ SsmlVoiceGender,
+ SynthesisInput,
+ SynthesizeSpeechRequest,
+ SynthesizeSpeechResponse,
+ Voice,
+ VoiceSelectionParams,
+)
+
+__all__ = (
+ "AudioConfig",
+ "CustomVoiceParams",
+ "ListVoicesRequest",
+ "ListVoicesResponse",
+ "SynthesisInput",
+ "SynthesizeSpeechRequest",
+ "SynthesizeSpeechResponse",
+ "Voice",
+ "VoiceSelectionParams",
+ "AudioEncoding",
+ "SsmlVoiceGender",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
new file mode 100644
index 000000000000..b70b7515fa60
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
@@ -0,0 +1,388 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import proto # type: ignore
+
+__protobuf__ = proto.module(
+ package="google.cloud.texttospeech.v1",
+ manifest={
+ "SsmlVoiceGender",
+ "AudioEncoding",
+ "ListVoicesRequest",
+ "ListVoicesResponse",
+ "Voice",
+ "SynthesizeSpeechRequest",
+ "SynthesisInput",
+ "VoiceSelectionParams",
+ "AudioConfig",
+ "CustomVoiceParams",
+ "SynthesizeSpeechResponse",
+ },
+)
+
+
+class SsmlVoiceGender(proto.Enum):
+ r"""Gender of the voice as described in `SSML voice
+ element `__.
+ """
+ SSML_VOICE_GENDER_UNSPECIFIED = 0
+ MALE = 1
+ FEMALE = 2
+ NEUTRAL = 3
+
+
+class AudioEncoding(proto.Enum):
+ r"""Configuration to set up audio encoder. The encoding
+ determines the output audio format that we'd like.
+ """
+ AUDIO_ENCODING_UNSPECIFIED = 0
+ LINEAR16 = 1
+ MP3 = 2
+ OGG_OPUS = 3
+ MULAW = 5
+ ALAW = 6
+
+
+class ListVoicesRequest(proto.Message):
+ r"""The top-level message sent by the client for the ``ListVoices``
+ method.
+
+ Attributes:
+ language_code (str):
+ Optional. Recommended.
+ `BCP-47 `__
+ language tag. If not specified, the API will return all
+ supported voices. If specified, the ListVoices call will
+ only return voices that can be used to synthesize this
+ language_code. For example, if you specify ``"en-NZ"``, all
+ ``"en-NZ"`` voices will be returned. If you specify
+ ``"no"``, both ``"no-\*"`` (Norwegian) and ``"nb-\*"``
+ (Norwegian Bokmal) voices will be returned.
+ """
+
+ language_code = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class ListVoicesResponse(proto.Message):
+ r"""The message returned to the client by the ``ListVoices`` method.
+
+ Attributes:
+ voices (Sequence[google.cloud.texttospeech_v1.types.Voice]):
+ The list of voices.
+ """
+
+ voices = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="Voice",
+ )
+
+
+class Voice(proto.Message):
+ r"""Description of a voice supported by the TTS service.
+
+ Attributes:
+ language_codes (Sequence[str]):
+ The languages that this voice supports, expressed as
+ `BCP-47 `__
+ language tags (e.g. "en-US", "es-419", "cmn-tw").
+ name (str):
+ The name of this voice. Each distinct voice
+ has a unique name.
+ ssml_gender (google.cloud.texttospeech_v1.types.SsmlVoiceGender):
+ The gender of this voice.
+ natural_sample_rate_hertz (int):
+ The natural sample rate (in hertz) for this
+ voice.
+ """
+
+ language_codes = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+ name = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+ ssml_gender = proto.Field(
+ proto.ENUM,
+ number=3,
+ enum="SsmlVoiceGender",
+ )
+ natural_sample_rate_hertz = proto.Field(
+ proto.INT32,
+ number=4,
+ )
+
+
+class SynthesizeSpeechRequest(proto.Message):
+ r"""The top-level message sent by the client for the
+ ``SynthesizeSpeech`` method.
+
+ Attributes:
+ input (google.cloud.texttospeech_v1.types.SynthesisInput):
+ Required. The Synthesizer requires either
+ plain text or SSML as input.
+ voice (google.cloud.texttospeech_v1.types.VoiceSelectionParams):
+ Required. The desired voice of the
+ synthesized audio.
+ audio_config (google.cloud.texttospeech_v1.types.AudioConfig):
+ Required. The configuration of the
+ synthesized audio.
+ """
+
+ input = proto.Field(
+ proto.MESSAGE,
+ number=1,
+ message="SynthesisInput",
+ )
+ voice = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message="VoiceSelectionParams",
+ )
+ audio_config = proto.Field(
+ proto.MESSAGE,
+ number=3,
+ message="AudioConfig",
+ )
+
+
+class SynthesisInput(proto.Message):
+ r"""Contains text input to be synthesized. Either ``text`` or ``ssml``
+ must be supplied. Supplying both or neither returns
+ [google.rpc.Code.INVALID_ARGUMENT][]. The input size is limited to
+ 5000 characters.
+
+ 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:
+ text (str):
+ The raw text to be synthesized.
+
+ This field is a member of `oneof`_ ``input_source``.
+ ssml (str):
+ The SSML document to be synthesized. The SSML document must
+ be valid and well-formed. Otherwise the RPC will fail and
+ return [google.rpc.Code.INVALID_ARGUMENT][]. For more
+ information, see
+ `SSML `__.
+
+ This field is a member of `oneof`_ ``input_source``.
+ """
+
+ text = proto.Field(
+ proto.STRING,
+ number=1,
+ oneof="input_source",
+ )
+ ssml = proto.Field(
+ proto.STRING,
+ number=2,
+ oneof="input_source",
+ )
+
+
+class VoiceSelectionParams(proto.Message):
+ r"""Description of which voice to use for a synthesis request.
+
+ Attributes:
+ language_code (str):
+ Required. The language (and potentially also the region) of
+ the voice expressed as a
+ `BCP-47 `__
+ language tag, e.g. "en-US". This should not include a script
+ tag (e.g. use "cmn-cn" rather than "cmn-Hant-cn"), because
+ the script will be inferred from the input provided in the
+ SynthesisInput. The TTS service will use this parameter to
+ help choose an appropriate voice. Note that the TTS service
+ may choose a voice with a slightly different language code
+ than the one selected; it may substitute a different region
+ (e.g. using en-US rather than en-CA if there isn't a
+ Canadian voice available), or even a different language,
+ e.g. using "nb" (Norwegian Bokmal) instead of "no"
+ (Norwegian)".
+ name (str):
+ The name of the voice. If not set, the service will choose a
+ voice based on the other parameters such as language_code
+ and gender.
+ ssml_gender (google.cloud.texttospeech_v1.types.SsmlVoiceGender):
+ The preferred gender of the voice. If not set, the service
+ will choose a voice based on the other parameters such as
+ language_code and name. Note that this is only a preference,
+ not requirement; if a voice of the appropriate gender is not
+ available, the synthesizer should substitute a voice with a
+ different gender rather than failing the request.
+ custom_voice (google.cloud.texttospeech_v1.types.CustomVoiceParams):
+ The configuration for a custom voice. If
+ [CustomVoiceParams.model] is set, the service will choose
+ the custom voice matching the specified configuration.
+ """
+
+ language_code = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ name = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+ ssml_gender = proto.Field(
+ proto.ENUM,
+ number=3,
+ enum="SsmlVoiceGender",
+ )
+ custom_voice = proto.Field(
+ proto.MESSAGE,
+ number=4,
+ message="CustomVoiceParams",
+ )
+
+
+class AudioConfig(proto.Message):
+ r"""Description of audio data to be synthesized.
+
+ Attributes:
+ audio_encoding (google.cloud.texttospeech_v1.types.AudioEncoding):
+ Required. The format of the audio byte
+ stream.
+ speaking_rate (float):
+ Optional. Input only. Speaking rate/speed, in the range
+ [0.25, 4.0]. 1.0 is the normal native speed supported by the
+ specific voice. 2.0 is twice as fast, and 0.5 is half as
+ fast. If unset(0.0), defaults to the native 1.0 speed. Any
+ other values < 0.25 or > 4.0 will return an error.
+ pitch (float):
+ Optional. Input only. Speaking pitch, in the range [-20.0,
+ 20.0]. 20 means increase 20 semitones from the original
+ pitch. -20 means decrease 20 semitones from the original
+ pitch.
+ volume_gain_db (float):
+ Optional. Input only. Volume gain (in dB) of the normal
+ native volume supported by the specific voice, in the range
+ [-96.0, 16.0]. If unset, or set to a value of 0.0 (dB), will
+ play at normal native signal amplitude. A value of -6.0 (dB)
+ will play at approximately half the amplitude of the normal
+ native signal amplitude. A value of +6.0 (dB) will play at
+ approximately twice the amplitude of the normal native
+ signal amplitude. Strongly recommend not to exceed +10 (dB)
+ as there's usually no effective increase in loudness for any
+ value greater than that.
+ sample_rate_hertz (int):
+ Optional. The synthesis sample rate (in hertz) for this
+ audio. When this is specified in SynthesizeSpeechRequest, if
+ this is different from the voice's natural sample rate, then
+ the synthesizer will honor this request by converting to the
+ desired sample rate (which might result in worse audio
+ quality), unless the specified sample rate is not supported
+ for the encoding chosen, in which case it will fail the
+ request and return [google.rpc.Code.INVALID_ARGUMENT][].
+ effects_profile_id (Sequence[str]):
+ Optional. Input only. An identifier which selects 'audio
+ effects' profiles that are applied on (post synthesized)
+ text to speech. Effects are applied on top of each other in
+ the order they are given. See `audio
+ profiles `__
+ for current supported profile ids.
+ """
+
+ audio_encoding = proto.Field(
+ proto.ENUM,
+ number=1,
+ enum="AudioEncoding",
+ )
+ speaking_rate = proto.Field(
+ proto.DOUBLE,
+ number=2,
+ )
+ pitch = proto.Field(
+ proto.DOUBLE,
+ number=3,
+ )
+ volume_gain_db = proto.Field(
+ proto.DOUBLE,
+ number=4,
+ )
+ sample_rate_hertz = proto.Field(
+ proto.INT32,
+ number=5,
+ )
+ effects_profile_id = proto.RepeatedField(
+ proto.STRING,
+ number=6,
+ )
+
+
+class CustomVoiceParams(proto.Message):
+ r"""Description of the custom voice to be synthesized.
+
+ Attributes:
+ model (str):
+ Required. The name of the AutoML model that
+ synthesizes the custom voice.
+ reported_usage (google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage):
+ Optional. The usage of the synthesized audio
+ to be reported.
+ """
+
+ class ReportedUsage(proto.Enum):
+ r"""The usage of the synthesized audio. You must report your
+ honest and correct usage of the service as it's regulated by
+ contract and will cause significant difference in billing.
+ """
+ REPORTED_USAGE_UNSPECIFIED = 0
+ REALTIME = 1
+ OFFLINE = 2
+
+ model = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ reported_usage = proto.Field(
+ proto.ENUM,
+ number=3,
+ enum=ReportedUsage,
+ )
+
+
+class SynthesizeSpeechResponse(proto.Message):
+ r"""The message returned to the client by the ``SynthesizeSpeech``
+ method.
+
+ Attributes:
+ audio_content (bytes):
+ The audio data bytes encoded as specified in the request,
+ including the header for encodings that are wrapped in
+ containers (e.g. MP3, OGG_OPUS). For LINEAR16 audio, we
+ include the WAV header. Note: as with all bytes fields,
+ protobuffers use a pure binary representation, whereas JSON
+ representations use base64.
+ """
+
+ audio_content = proto.Field(
+ proto.BYTES,
+ number=1,
+ )
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/__init__.py
new file mode 100644
index 000000000000..c7a1e4dd4b80
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/__init__.py
@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from .services.text_to_speech import TextToSpeechAsyncClient, TextToSpeechClient
+from .types.cloud_tts import (
+ AudioConfig,
+ AudioEncoding,
+ CustomVoiceParams,
+ ListVoicesRequest,
+ ListVoicesResponse,
+ SsmlVoiceGender,
+ SynthesisInput,
+ SynthesizeSpeechRequest,
+ SynthesizeSpeechResponse,
+ Timepoint,
+ Voice,
+ VoiceSelectionParams,
+)
+
+__all__ = (
+ "TextToSpeechAsyncClient",
+ "AudioConfig",
+ "AudioEncoding",
+ "CustomVoiceParams",
+ "ListVoicesRequest",
+ "ListVoicesResponse",
+ "SsmlVoiceGender",
+ "SynthesisInput",
+ "SynthesizeSpeechRequest",
+ "SynthesizeSpeechResponse",
+ "TextToSpeechClient",
+ "Timepoint",
+ "Voice",
+ "VoiceSelectionParams",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/gapic_metadata.json b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/gapic_metadata.json
new file mode 100644
index 000000000000..2a31677f51b1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/gapic_metadata.json
@@ -0,0 +1,43 @@
+ {
+ "comment": "This file maps proto services/RPCs to the corresponding library clients/methods",
+ "language": "python",
+ "libraryPackage": "google.cloud.texttospeech_v1beta1",
+ "protoPackage": "google.cloud.texttospeech.v1beta1",
+ "schema": "1.0",
+ "services": {
+ "TextToSpeech": {
+ "clients": {
+ "grpc": {
+ "libraryClient": "TextToSpeechClient",
+ "rpcs": {
+ "ListVoices": {
+ "methods": [
+ "list_voices"
+ ]
+ },
+ "SynthesizeSpeech": {
+ "methods": [
+ "synthesize_speech"
+ ]
+ }
+ }
+ },
+ "grpc-async": {
+ "libraryClient": "TextToSpeechAsyncClient",
+ "rpcs": {
+ "ListVoices": {
+ "methods": [
+ "list_voices"
+ ]
+ },
+ "SynthesizeSpeech": {
+ "methods": [
+ "synthesize_speech"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/py.typed b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/py.typed
new file mode 100644
index 000000000000..9b87c1e1cbf9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/py.typed
@@ -0,0 +1,2 @@
+# Marker file for PEP 561.
+# The google-cloud-texttospeech package uses inline types.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/__init__.py
new file mode 100644
index 000000000000..e8e1c3845db5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/__init__.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/__init__.py
new file mode 100644
index 000000000000..f70edab7c5c7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from .async_client import TextToSpeechAsyncClient
+from .client import TextToSpeechClient
+
+__all__ = (
+ "TextToSpeechClient",
+ "TextToSpeechAsyncClient",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
new file mode 100644
index 000000000000..fdadf8855dcd
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
@@ -0,0 +1,448 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import functools
+import re
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
+
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.api_core.client_options import ClientOptions
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+import pkg_resources
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.cloud.texttospeech_v1beta1.types import cloud_tts
+
+from .client import TextToSpeechClient
+from .transports.base import DEFAULT_CLIENT_INFO, TextToSpeechTransport
+from .transports.grpc_asyncio import TextToSpeechGrpcAsyncIOTransport
+
+
+class TextToSpeechAsyncClient:
+ """Service that implements Google Cloud Text-to-Speech API."""
+
+ _client: TextToSpeechClient
+
+ DEFAULT_ENDPOINT = TextToSpeechClient.DEFAULT_ENDPOINT
+ DEFAULT_MTLS_ENDPOINT = TextToSpeechClient.DEFAULT_MTLS_ENDPOINT
+
+ model_path = staticmethod(TextToSpeechClient.model_path)
+ parse_model_path = staticmethod(TextToSpeechClient.parse_model_path)
+ common_billing_account_path = staticmethod(
+ TextToSpeechClient.common_billing_account_path
+ )
+ parse_common_billing_account_path = staticmethod(
+ TextToSpeechClient.parse_common_billing_account_path
+ )
+ common_folder_path = staticmethod(TextToSpeechClient.common_folder_path)
+ parse_common_folder_path = staticmethod(TextToSpeechClient.parse_common_folder_path)
+ common_organization_path = staticmethod(TextToSpeechClient.common_organization_path)
+ parse_common_organization_path = staticmethod(
+ TextToSpeechClient.parse_common_organization_path
+ )
+ common_project_path = staticmethod(TextToSpeechClient.common_project_path)
+ parse_common_project_path = staticmethod(
+ TextToSpeechClient.parse_common_project_path
+ )
+ common_location_path = staticmethod(TextToSpeechClient.common_location_path)
+ parse_common_location_path = staticmethod(
+ TextToSpeechClient.parse_common_location_path
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ TextToSpeechAsyncClient: The constructed client.
+ """
+ return TextToSpeechClient.from_service_account_info.__func__(TextToSpeechAsyncClient, info, *args, **kwargs) # type: ignore
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ TextToSpeechAsyncClient: The constructed client.
+ """
+ return TextToSpeechClient.from_service_account_file.__func__(TextToSpeechAsyncClient, filename, *args, **kwargs) # type: ignore
+
+ from_service_account_json = from_service_account_file
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ return TextToSpeechClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore
+
+ @property
+ def transport(self) -> TextToSpeechTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ TextToSpeechTransport: The transport used by the client instance.
+ """
+ return self._client.transport
+
+ get_transport_class = functools.partial(
+ type(TextToSpeechClient).get_transport_class, type(TextToSpeechClient)
+ )
+
+ def __init__(
+ self,
+ *,
+ credentials: ga_credentials.Credentials = None,
+ transport: Union[str, TextToSpeechTransport] = "grpc_asyncio",
+ client_options: ClientOptions = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the text to speech client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, ~.TextToSpeechTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (ClientOptions): Custom options for the client. It
+ won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ self._client = TextToSpeechClient(
+ credentials=credentials,
+ transport=transport,
+ client_options=client_options,
+ client_info=client_info,
+ )
+
+ async def list_voices(
+ self,
+ request: Union[cloud_tts.ListVoicesRequest, dict] = None,
+ *,
+ language_code: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.ListVoicesResponse:
+ r"""Returns a list of Voice supported for synthesis.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google.cloud import texttospeech_v1beta1
+
+ async def sample_list_voices():
+ # Create a client
+ client = texttospeech_v1beta1.TextToSpeechAsyncClient()
+
+ # Initialize request argument(s)
+ request = texttospeech_v1beta1.ListVoicesRequest(
+ )
+
+ # Make the request
+ response = await client.list_voices(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.cloud.texttospeech_v1beta1.types.ListVoicesRequest, dict]):
+ The request object. The top-level message sent by the
+ client for the `ListVoices` method.
+ language_code (:class:`str`):
+ Optional. Recommended.
+ `BCP-47 `__
+ language tag. If not specified, the API will return all
+ supported voices. If specified, the ListVoices call will
+ only return voices that can be used to synthesize this
+ language_code. For example, if you specify ``"en-NZ"``,
+ all ``"en-NZ"`` voices will be returned. If you specify
+ ``"no"``, both ``"no-\*"`` (Norwegian) and ``"nb-\*"``
+ (Norwegian Bokmal) voices will be returned.
+
+ This corresponds to the ``language_code`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1beta1.types.ListVoicesResponse:
+ The message returned to the client by the ListVoices
+ method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([language_code])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = cloud_tts.ListVoicesRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if language_code is not None:
+ request.language_code = language_code
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_voices,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def synthesize_speech(
+ self,
+ request: Union[cloud_tts.SynthesizeSpeechRequest, dict] = None,
+ *,
+ input: cloud_tts.SynthesisInput = None,
+ voice: cloud_tts.VoiceSelectionParams = None,
+ audio_config: cloud_tts.AudioConfig = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.SynthesizeSpeechResponse:
+ r"""Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google.cloud import texttospeech_v1beta1
+
+ async def sample_synthesize_speech():
+ # Create a client
+ client = texttospeech_v1beta1.TextToSpeechAsyncClient()
+
+ # Initialize request argument(s)
+ input = texttospeech_v1beta1.SynthesisInput()
+ input.text = "text_value"
+
+ voice = texttospeech_v1beta1.VoiceSelectionParams()
+ voice.language_code = "language_code_value"
+
+ audio_config = texttospeech_v1beta1.AudioConfig()
+ audio_config.audio_encoding = "ALAW"
+
+ request = texttospeech_v1beta1.SynthesizeSpeechRequest(
+ input=input,
+ voice=voice,
+ audio_config=audio_config,
+ )
+
+ # Make the request
+ response = await client.synthesize_speech(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest, dict]):
+ The request object. The top-level message sent by the
+ client for the `SynthesizeSpeech` method.
+ input (:class:`google.cloud.texttospeech_v1beta1.types.SynthesisInput`):
+ Required. The Synthesizer requires
+ either plain text or SSML as input.
+
+ This corresponds to the ``input`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ voice (:class:`google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams`):
+ Required. The desired voice of the
+ synthesized audio.
+
+ This corresponds to the ``voice`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ audio_config (:class:`google.cloud.texttospeech_v1beta1.types.AudioConfig`):
+ Required. The configuration of the
+ synthesized audio.
+
+ This corresponds to the ``audio_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse:
+ The message returned to the client by the
+ SynthesizeSpeech method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([input, voice, audio_config])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = cloud_tts.SynthesizeSpeechRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if input is not None:
+ request.input = input
+ if voice is not None:
+ request.voice = voice
+ if audio_config is not None:
+ request.audio_config = audio_config
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.synthesize_speech,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb):
+ await self.transport.close()
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ gapic_version=pkg_resources.get_distribution(
+ "google-cloud-texttospeech",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("TextToSpeechAsyncClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
new file mode 100644
index 000000000000..c67467d3f51b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
@@ -0,0 +1,682 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import os
+import re
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
+
+from google.api_core import client_options as client_options_lib
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.exceptions import MutualTLSChannelError # type: ignore
+from google.auth.transport import mtls # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+import pkg_resources
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.cloud.texttospeech_v1beta1.types import cloud_tts
+
+from .transports.base import DEFAULT_CLIENT_INFO, TextToSpeechTransport
+from .transports.grpc import TextToSpeechGrpcTransport
+from .transports.grpc_asyncio import TextToSpeechGrpcAsyncIOTransport
+
+
+class TextToSpeechClientMeta(type):
+ """Metaclass for the TextToSpeech client.
+
+ This provides class-level methods for building and retrieving
+ support objects (e.g. transport) without polluting the client instance
+ objects.
+ """
+
+ _transport_registry = OrderedDict() # type: Dict[str, Type[TextToSpeechTransport]]
+ _transport_registry["grpc"] = TextToSpeechGrpcTransport
+ _transport_registry["grpc_asyncio"] = TextToSpeechGrpcAsyncIOTransport
+
+ def get_transport_class(
+ cls,
+ label: str = None,
+ ) -> Type[TextToSpeechTransport]:
+ """Returns an appropriate transport class.
+
+ Args:
+ label: The name of the desired transport. If none is
+ provided, then the first transport in the registry is used.
+
+ Returns:
+ The transport class to use.
+ """
+ # If a specific transport is requested, return that one.
+ if label:
+ return cls._transport_registry[label]
+
+ # No transport is requested; return the default (that is, the first one
+ # in the dictionary).
+ return next(iter(cls._transport_registry.values()))
+
+
+class TextToSpeechClient(metaclass=TextToSpeechClientMeta):
+ """Service that implements Google Cloud Text-to-Speech API."""
+
+ @staticmethod
+ def _get_default_mtls_endpoint(api_endpoint):
+ """Converts api endpoint to mTLS endpoint.
+
+ Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
+ "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
+ Args:
+ api_endpoint (Optional[str]): the api endpoint to convert.
+ Returns:
+ str: converted mTLS api endpoint.
+ """
+ if not api_endpoint:
+ return api_endpoint
+
+ mtls_endpoint_re = re.compile(
+ r"(?P[^.]+)(?P\.mtls)?(?P\.sandbox)?(?P\.googleapis\.com)?"
+ )
+
+ m = mtls_endpoint_re.match(api_endpoint)
+ name, mtls, sandbox, googledomain = m.groups()
+ if mtls or not googledomain:
+ return api_endpoint
+
+ if sandbox:
+ return api_endpoint.replace(
+ "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
+ )
+
+ return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
+
+ DEFAULT_ENDPOINT = "texttospeech.googleapis.com"
+ DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore
+ DEFAULT_ENDPOINT
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ TextToSpeechClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_info(info)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ TextToSpeechClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_file(filename)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ from_service_account_json = from_service_account_file
+
+ @property
+ def transport(self) -> TextToSpeechTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ TextToSpeechTransport: The transport used by the client
+ instance.
+ """
+ return self._transport
+
+ @staticmethod
+ def model_path(
+ project: str,
+ location: str,
+ model: str,
+ ) -> str:
+ """Returns a fully-qualified model string."""
+ return "projects/{project}/locations/{location}/models/{model}".format(
+ project=project,
+ location=location,
+ model=model,
+ )
+
+ @staticmethod
+ def parse_model_path(path: str) -> Dict[str, str]:
+ """Parses a model path into its component segments."""
+ m = re.match(
+ r"^projects/(?P.+?)/locations/(?P.+?)/models/(?P.+?)$",
+ path,
+ )
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_billing_account_path(
+ billing_account: str,
+ ) -> str:
+ """Returns a fully-qualified billing_account string."""
+ return "billingAccounts/{billing_account}".format(
+ billing_account=billing_account,
+ )
+
+ @staticmethod
+ def parse_common_billing_account_path(path: str) -> Dict[str, str]:
+ """Parse a billing_account path into its component segments."""
+ m = re.match(r"^billingAccounts/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_folder_path(
+ folder: str,
+ ) -> str:
+ """Returns a fully-qualified folder string."""
+ return "folders/{folder}".format(
+ folder=folder,
+ )
+
+ @staticmethod
+ def parse_common_folder_path(path: str) -> Dict[str, str]:
+ """Parse a folder path into its component segments."""
+ m = re.match(r"^folders/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_organization_path(
+ organization: str,
+ ) -> str:
+ """Returns a fully-qualified organization string."""
+ return "organizations/{organization}".format(
+ organization=organization,
+ )
+
+ @staticmethod
+ def parse_common_organization_path(path: str) -> Dict[str, str]:
+ """Parse a organization path into its component segments."""
+ m = re.match(r"^organizations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_project_path(
+ project: str,
+ ) -> str:
+ """Returns a fully-qualified project string."""
+ return "projects/{project}".format(
+ project=project,
+ )
+
+ @staticmethod
+ def parse_common_project_path(path: str) -> Dict[str, str]:
+ """Parse a project path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_location_path(
+ project: str,
+ location: str,
+ ) -> str:
+ """Returns a fully-qualified location string."""
+ return "projects/{project}/locations/{location}".format(
+ project=project,
+ location=location,
+ )
+
+ @staticmethod
+ def parse_common_location_path(path: str) -> Dict[str, str]:
+ """Parse a location path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/locations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[client_options_lib.ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+ use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
+ use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
+ if use_client_cert not in ("true", "false"):
+ raise ValueError(
+ "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"
+ )
+ if use_mtls_endpoint not in ("auto", "never", "always"):
+ raise MutualTLSChannelError(
+ "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"
+ )
+
+ # Figure out the client cert source to use.
+ client_cert_source = None
+ if use_client_cert == "true":
+ if client_options.client_cert_source:
+ client_cert_source = client_options.client_cert_source
+ elif mtls.has_default_client_cert_source():
+ client_cert_source = mtls.default_client_cert_source()
+
+ # Figure out which api endpoint to use.
+ if client_options.api_endpoint is not None:
+ api_endpoint = client_options.api_endpoint
+ elif use_mtls_endpoint == "always" or (
+ use_mtls_endpoint == "auto" and client_cert_source
+ ):
+ api_endpoint = cls.DEFAULT_MTLS_ENDPOINT
+ else:
+ api_endpoint = cls.DEFAULT_ENDPOINT
+
+ return api_endpoint, client_cert_source
+
+ def __init__(
+ self,
+ *,
+ credentials: Optional[ga_credentials.Credentials] = None,
+ transport: Union[str, TextToSpeechTransport, None] = None,
+ client_options: Optional[client_options_lib.ClientOptions] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the text to speech client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, TextToSpeechTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. It won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ if isinstance(client_options, dict):
+ client_options = client_options_lib.from_dict(client_options)
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+
+ api_endpoint, client_cert_source_func = self.get_mtls_endpoint_and_cert_source(
+ client_options
+ )
+
+ api_key_value = getattr(client_options, "api_key", None)
+ if api_key_value and credentials:
+ raise ValueError(
+ "client_options.api_key and credentials are mutually exclusive"
+ )
+
+ # Save or instantiate the transport.
+ # Ordinarily, we provide the transport, but allowing a custom transport
+ # instance provides an extensibility point for unusual situations.
+ if isinstance(transport, TextToSpeechTransport):
+ # transport is a TextToSpeechTransport instance.
+ if credentials or client_options.credentials_file or api_key_value:
+ raise ValueError(
+ "When providing a transport instance, "
+ "provide its credentials directly."
+ )
+ if client_options.scopes:
+ raise ValueError(
+ "When providing a transport instance, provide its scopes "
+ "directly."
+ )
+ self._transport = transport
+ else:
+ import google.auth._default # type: ignore
+
+ if api_key_value and hasattr(
+ google.auth._default, "get_api_key_credentials"
+ ):
+ credentials = google.auth._default.get_api_key_credentials(
+ api_key_value
+ )
+
+ Transport = type(self).get_transport_class(transport)
+ self._transport = Transport(
+ credentials=credentials,
+ credentials_file=client_options.credentials_file,
+ host=api_endpoint,
+ scopes=client_options.scopes,
+ client_cert_source_for_mtls=client_cert_source_func,
+ quota_project_id=client_options.quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=True,
+ api_audience=client_options.api_audience,
+ )
+
+ def list_voices(
+ self,
+ request: Union[cloud_tts.ListVoicesRequest, dict] = None,
+ *,
+ language_code: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.ListVoicesResponse:
+ r"""Returns a list of Voice supported for synthesis.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google.cloud import texttospeech_v1beta1
+
+ def sample_list_voices():
+ # Create a client
+ client = texttospeech_v1beta1.TextToSpeechClient()
+
+ # Initialize request argument(s)
+ request = texttospeech_v1beta1.ListVoicesRequest(
+ )
+
+ # Make the request
+ response = client.list_voices(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.cloud.texttospeech_v1beta1.types.ListVoicesRequest, dict]):
+ The request object. The top-level message sent by the
+ client for the `ListVoices` method.
+ language_code (str):
+ Optional. Recommended.
+ `BCP-47 `__
+ language tag. If not specified, the API will return all
+ supported voices. If specified, the ListVoices call will
+ only return voices that can be used to synthesize this
+ language_code. For example, if you specify ``"en-NZ"``,
+ all ``"en-NZ"`` voices will be returned. If you specify
+ ``"no"``, both ``"no-\*"`` (Norwegian) and ``"nb-\*"``
+ (Norwegian Bokmal) voices will be returned.
+
+ This corresponds to the ``language_code`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1beta1.types.ListVoicesResponse:
+ The message returned to the client by the ListVoices
+ method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([language_code])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a cloud_tts.ListVoicesRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, cloud_tts.ListVoicesRequest):
+ request = cloud_tts.ListVoicesRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if language_code is not None:
+ request.language_code = language_code
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_voices]
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def synthesize_speech(
+ self,
+ request: Union[cloud_tts.SynthesizeSpeechRequest, dict] = None,
+ *,
+ input: cloud_tts.SynthesisInput = None,
+ voice: cloud_tts.VoiceSelectionParams = None,
+ audio_config: cloud_tts.AudioConfig = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.SynthesizeSpeechResponse:
+ r"""Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google.cloud import texttospeech_v1beta1
+
+ def sample_synthesize_speech():
+ # Create a client
+ client = texttospeech_v1beta1.TextToSpeechClient()
+
+ # Initialize request argument(s)
+ input = texttospeech_v1beta1.SynthesisInput()
+ input.text = "text_value"
+
+ voice = texttospeech_v1beta1.VoiceSelectionParams()
+ voice.language_code = "language_code_value"
+
+ audio_config = texttospeech_v1beta1.AudioConfig()
+ audio_config.audio_encoding = "ALAW"
+
+ request = texttospeech_v1beta1.SynthesizeSpeechRequest(
+ input=input,
+ voice=voice,
+ audio_config=audio_config,
+ )
+
+ # Make the request
+ response = client.synthesize_speech(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest, dict]):
+ The request object. The top-level message sent by the
+ client for the `SynthesizeSpeech` method.
+ input (google.cloud.texttospeech_v1beta1.types.SynthesisInput):
+ Required. The Synthesizer requires
+ either plain text or SSML as input.
+
+ This corresponds to the ``input`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ voice (google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams):
+ Required. The desired voice of the
+ synthesized audio.
+
+ This corresponds to the ``voice`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ audio_config (google.cloud.texttospeech_v1beta1.types.AudioConfig):
+ Required. The configuration of the
+ synthesized audio.
+
+ This corresponds to the ``audio_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse:
+ The message returned to the client by the
+ SynthesizeSpeech method.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([input, voice, audio_config])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a cloud_tts.SynthesizeSpeechRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, cloud_tts.SynthesizeSpeechRequest):
+ request = cloud_tts.SynthesizeSpeechRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if input is not None:
+ request.input = input
+ if voice is not None:
+ request.voice = voice
+ if audio_config is not None:
+ request.audio_config = audio_config
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.synthesize_speech]
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, type, value, traceback):
+ """Releases underlying transport's resources.
+
+ .. warning::
+ ONLY use as a context manager if the transport is NOT shared
+ with other clients! Exiting the with block will CLOSE the transport
+ and may cause errors in other clients!
+ """
+ self.transport.close()
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ gapic_version=pkg_resources.get_distribution(
+ "google-cloud-texttospeech",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("TextToSpeechClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/__init__.py
new file mode 100644
index 000000000000..9a13500994d8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/__init__.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+from typing import Dict, Type
+
+from .base import TextToSpeechTransport
+from .grpc import TextToSpeechGrpcTransport
+from .grpc_asyncio import TextToSpeechGrpcAsyncIOTransport
+
+# Compile a registry of transports.
+_transport_registry = OrderedDict() # type: Dict[str, Type[TextToSpeechTransport]]
+_transport_registry["grpc"] = TextToSpeechGrpcTransport
+_transport_registry["grpc_asyncio"] = TextToSpeechGrpcAsyncIOTransport
+
+__all__ = (
+ "TextToSpeechTransport",
+ "TextToSpeechGrpcTransport",
+ "TextToSpeechGrpcAsyncIOTransport",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/base.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/base.py
new file mode 100644
index 000000000000..c3e04552e701
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/base.py
@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import abc
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Union
+
+import google.api_core
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+import google.auth # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+import pkg_resources
+
+from google.cloud.texttospeech_v1beta1.types import cloud_tts
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ gapic_version=pkg_resources.get_distribution(
+ "google-cloud-texttospeech",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+class TextToSpeechTransport(abc.ABC):
+ """Abstract transport class for TextToSpeech."""
+
+ AUTH_SCOPES = ("https://www.googleapis.com/auth/cloud-platform",)
+
+ DEFAULT_HOST: str = "texttospeech.googleapis.com"
+
+ def __init__(
+ self,
+ *,
+ host: str = DEFAULT_HOST,
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ **kwargs,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A list of scopes.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+ """
+
+ scopes_kwargs = {"scopes": scopes, "default_scopes": self.AUTH_SCOPES}
+
+ # Save the scopes.
+ self._scopes = scopes
+
+ # If no credentials are provided, then determine the appropriate
+ # defaults.
+ if credentials and credentials_file:
+ raise core_exceptions.DuplicateCredentialArgs(
+ "'credentials_file' and 'credentials' are mutually exclusive"
+ )
+
+ if credentials_file is not None:
+ credentials, _ = google.auth.load_credentials_from_file(
+ credentials_file, **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ elif credentials is None:
+ credentials, _ = google.auth.default(
+ **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ # Don't apply audience if the credentials file passed from user.
+ if hasattr(credentials, "with_gdch_audience"):
+ credentials = credentials.with_gdch_audience(
+ api_audience if api_audience else host
+ )
+
+ # If the credentials are service account credentials, then always try to use self signed JWT.
+ if (
+ always_use_jwt_access
+ and isinstance(credentials, service_account.Credentials)
+ and hasattr(service_account.Credentials, "with_always_use_jwt_access")
+ ):
+ credentials = credentials.with_always_use_jwt_access(True)
+
+ # Save the credentials.
+ self._credentials = credentials
+
+ # Save the hostname. Default to port 443 (HTTPS) if none is specified.
+ if ":" not in host:
+ host += ":443"
+ self._host = host
+
+ def _prep_wrapped_messages(self, client_info):
+ # Precompute the wrapped methods.
+ self._wrapped_methods = {
+ self.list_voices: gapic_v1.method.wrap_method(
+ self.list_voices,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ self.synthesize_speech: gapic_v1.method.wrap_method(
+ self.synthesize_speech,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ }
+
+ def close(self):
+ """Closes resources associated with the transport.
+
+ .. warning::
+ Only call this method if the transport is NOT shared
+ with other clients - this may cause errors in other clients!
+ """
+ raise NotImplementedError()
+
+ @property
+ def list_voices(
+ self,
+ ) -> Callable[
+ [cloud_tts.ListVoicesRequest],
+ Union[cloud_tts.ListVoicesResponse, Awaitable[cloud_tts.ListVoicesResponse]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def synthesize_speech(
+ self,
+ ) -> Callable[
+ [cloud_tts.SynthesizeSpeechRequest],
+ Union[
+ cloud_tts.SynthesizeSpeechResponse,
+ Awaitable[cloud_tts.SynthesizeSpeechResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def kind(self) -> str:
+ raise NotImplementedError()
+
+
+__all__ = ("TextToSpeechTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/grpc.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/grpc.py
new file mode 100644
index 000000000000..b09b58170ca9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/grpc.py
@@ -0,0 +1,294 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import Callable, Dict, Optional, Sequence, Tuple, Union
+import warnings
+
+from google.api_core import gapic_v1, grpc_helpers
+import google.auth # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+import grpc # type: ignore
+
+from google.cloud.texttospeech_v1beta1.types import cloud_tts
+
+from .base import DEFAULT_CLIENT_INFO, TextToSpeechTransport
+
+
+class TextToSpeechGrpcTransport(TextToSpeechTransport):
+ """gRPC backend transport for TextToSpeech.
+
+ Service that implements Google Cloud Text-to-Speech API.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _stubs: Dict[str, Callable]
+
+ def __init__(
+ self,
+ *,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Sequence[str] = None,
+ channel: grpc.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional(Sequence[str])): A list of scopes. This argument is
+ ignored if ``channel`` is provided.
+ channel (Optional[grpc.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> grpc.Channel:
+ """Create and return a gRPC channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ grpc.Channel: A gRPC channel object.
+
+ Raises:
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+
+ return grpc_helpers.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ @property
+ def grpc_channel(self) -> grpc.Channel:
+ """Return the channel designed to connect to this service."""
+ return self._grpc_channel
+
+ @property
+ def list_voices(
+ self,
+ ) -> Callable[[cloud_tts.ListVoicesRequest], cloud_tts.ListVoicesResponse]:
+ r"""Return a callable for the list voices method over gRPC.
+
+ Returns a list of Voice supported for synthesis.
+
+ Returns:
+ Callable[[~.ListVoicesRequest],
+ ~.ListVoicesResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_voices" not in self._stubs:
+ self._stubs["list_voices"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1beta1.TextToSpeech/ListVoices",
+ request_serializer=cloud_tts.ListVoicesRequest.serialize,
+ response_deserializer=cloud_tts.ListVoicesResponse.deserialize,
+ )
+ return self._stubs["list_voices"]
+
+ @property
+ def synthesize_speech(
+ self,
+ ) -> Callable[
+ [cloud_tts.SynthesizeSpeechRequest], cloud_tts.SynthesizeSpeechResponse
+ ]:
+ r"""Return a callable for the synthesize speech method over gRPC.
+
+ Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ Returns:
+ Callable[[~.SynthesizeSpeechRequest],
+ ~.SynthesizeSpeechResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "synthesize_speech" not in self._stubs:
+ self._stubs["synthesize_speech"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1beta1.TextToSpeech/SynthesizeSpeech",
+ request_serializer=cloud_tts.SynthesizeSpeechRequest.serialize,
+ response_deserializer=cloud_tts.SynthesizeSpeechResponse.deserialize,
+ )
+ return self._stubs["synthesize_speech"]
+
+ def close(self):
+ self.grpc_channel.close()
+
+ @property
+ def kind(self) -> str:
+ return "grpc"
+
+
+__all__ = ("TextToSpeechGrpcTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/grpc_asyncio.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/grpc_asyncio.py
new file mode 100644
index 000000000000..43974466147a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/transports/grpc_asyncio.py
@@ -0,0 +1,296 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Tuple, Union
+import warnings
+
+from google.api_core import gapic_v1, grpc_helpers_async
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+import grpc # type: ignore
+from grpc.experimental import aio # type: ignore
+
+from google.cloud.texttospeech_v1beta1.types import cloud_tts
+
+from .base import DEFAULT_CLIENT_INFO, TextToSpeechTransport
+from .grpc import TextToSpeechGrpcTransport
+
+
+class TextToSpeechGrpcAsyncIOTransport(TextToSpeechTransport):
+ """gRPC AsyncIO backend transport for TextToSpeech.
+
+ Service that implements Google Cloud Text-to-Speech API.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _grpc_channel: aio.Channel
+ _stubs: Dict[str, Callable] = {}
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> aio.Channel:
+ """Create and return a gRPC AsyncIO channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ aio.Channel: A gRPC AsyncIO channel object.
+ """
+
+ return grpc_helpers_async.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ def __init__(
+ self,
+ *,
+ host: str = "texttospeech.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ channel: aio.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id=None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ channel (Optional[aio.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @property
+ def grpc_channel(self) -> aio.Channel:
+ """Create the channel designed to connect to this service.
+
+ This property caches on the instance; repeated calls return
+ the same channel.
+ """
+ # Return the channel from cache.
+ return self._grpc_channel
+
+ @property
+ def list_voices(
+ self,
+ ) -> Callable[
+ [cloud_tts.ListVoicesRequest], Awaitable[cloud_tts.ListVoicesResponse]
+ ]:
+ r"""Return a callable for the list voices method over gRPC.
+
+ Returns a list of Voice supported for synthesis.
+
+ Returns:
+ Callable[[~.ListVoicesRequest],
+ Awaitable[~.ListVoicesResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_voices" not in self._stubs:
+ self._stubs["list_voices"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1beta1.TextToSpeech/ListVoices",
+ request_serializer=cloud_tts.ListVoicesRequest.serialize,
+ response_deserializer=cloud_tts.ListVoicesResponse.deserialize,
+ )
+ return self._stubs["list_voices"]
+
+ @property
+ def synthesize_speech(
+ self,
+ ) -> Callable[
+ [cloud_tts.SynthesizeSpeechRequest],
+ Awaitable[cloud_tts.SynthesizeSpeechResponse],
+ ]:
+ r"""Return a callable for the synthesize speech method over gRPC.
+
+ Synthesizes speech synchronously: receive results
+ after all text input has been processed.
+
+ Returns:
+ Callable[[~.SynthesizeSpeechRequest],
+ Awaitable[~.SynthesizeSpeechResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "synthesize_speech" not in self._stubs:
+ self._stubs["synthesize_speech"] = self.grpc_channel.unary_unary(
+ "/google.cloud.texttospeech.v1beta1.TextToSpeech/SynthesizeSpeech",
+ request_serializer=cloud_tts.SynthesizeSpeechRequest.serialize,
+ response_deserializer=cloud_tts.SynthesizeSpeechResponse.deserialize,
+ )
+ return self._stubs["synthesize_speech"]
+
+ def close(self):
+ return self.grpc_channel.close()
+
+
+__all__ = ("TextToSpeechGrpcAsyncIOTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/__init__.py
new file mode 100644
index 000000000000..2a34ccab0090
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/__init__.py
@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from .cloud_tts import (
+ AudioConfig,
+ AudioEncoding,
+ CustomVoiceParams,
+ ListVoicesRequest,
+ ListVoicesResponse,
+ SsmlVoiceGender,
+ SynthesisInput,
+ SynthesizeSpeechRequest,
+ SynthesizeSpeechResponse,
+ Timepoint,
+ Voice,
+ VoiceSelectionParams,
+)
+
+__all__ = (
+ "AudioConfig",
+ "CustomVoiceParams",
+ "ListVoicesRequest",
+ "ListVoicesResponse",
+ "SynthesisInput",
+ "SynthesizeSpeechRequest",
+ "SynthesizeSpeechResponse",
+ "Timepoint",
+ "Voice",
+ "VoiceSelectionParams",
+ "AudioEncoding",
+ "SsmlVoiceGender",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
new file mode 100644
index 000000000000..786961c5d61d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
@@ -0,0 +1,444 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import proto # type: ignore
+
+__protobuf__ = proto.module(
+ package="google.cloud.texttospeech.v1beta1",
+ manifest={
+ "SsmlVoiceGender",
+ "AudioEncoding",
+ "ListVoicesRequest",
+ "ListVoicesResponse",
+ "Voice",
+ "SynthesizeSpeechRequest",
+ "SynthesisInput",
+ "VoiceSelectionParams",
+ "AudioConfig",
+ "CustomVoiceParams",
+ "SynthesizeSpeechResponse",
+ "Timepoint",
+ },
+)
+
+
+class SsmlVoiceGender(proto.Enum):
+ r"""Gender of the voice as described in `SSML voice
+ element `__.
+ """
+ SSML_VOICE_GENDER_UNSPECIFIED = 0
+ MALE = 1
+ FEMALE = 2
+ NEUTRAL = 3
+
+
+class AudioEncoding(proto.Enum):
+ r"""Configuration to set up audio encoder. The encoding
+ determines the output audio format that we'd like.
+ """
+ AUDIO_ENCODING_UNSPECIFIED = 0
+ LINEAR16 = 1
+ MP3 = 2
+ MP3_64_KBPS = 4
+ OGG_OPUS = 3
+ MULAW = 5
+ ALAW = 6
+
+
+class ListVoicesRequest(proto.Message):
+ r"""The top-level message sent by the client for the ``ListVoices``
+ method.
+
+ Attributes:
+ language_code (str):
+ Optional. Recommended.
+ `BCP-47 `__
+ language tag. If not specified, the API will return all
+ supported voices. If specified, the ListVoices call will
+ only return voices that can be used to synthesize this
+ language_code. For example, if you specify ``"en-NZ"``, all
+ ``"en-NZ"`` voices will be returned. If you specify
+ ``"no"``, both ``"no-\*"`` (Norwegian) and ``"nb-\*"``
+ (Norwegian Bokmal) voices will be returned.
+ """
+
+ language_code = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class ListVoicesResponse(proto.Message):
+ r"""The message returned to the client by the ``ListVoices`` method.
+
+ Attributes:
+ voices (Sequence[google.cloud.texttospeech_v1beta1.types.Voice]):
+ The list of voices.
+ """
+
+ voices = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="Voice",
+ )
+
+
+class Voice(proto.Message):
+ r"""Description of a voice supported by the TTS service.
+
+ Attributes:
+ language_codes (Sequence[str]):
+ The languages that this voice supports, expressed as
+ `BCP-47 `__
+ language tags (e.g. "en-US", "es-419", "cmn-tw").
+ name (str):
+ The name of this voice. Each distinct voice
+ has a unique name.
+ ssml_gender (google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender):
+ The gender of this voice.
+ natural_sample_rate_hertz (int):
+ The natural sample rate (in hertz) for this
+ voice.
+ """
+
+ language_codes = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+ name = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+ ssml_gender = proto.Field(
+ proto.ENUM,
+ number=3,
+ enum="SsmlVoiceGender",
+ )
+ natural_sample_rate_hertz = proto.Field(
+ proto.INT32,
+ number=4,
+ )
+
+
+class SynthesizeSpeechRequest(proto.Message):
+ r"""The top-level message sent by the client for the
+ ``SynthesizeSpeech`` method.
+
+ Attributes:
+ input (google.cloud.texttospeech_v1beta1.types.SynthesisInput):
+ Required. The Synthesizer requires either
+ plain text or SSML as input.
+ voice (google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams):
+ Required. The desired voice of the
+ synthesized audio.
+ audio_config (google.cloud.texttospeech_v1beta1.types.AudioConfig):
+ Required. The configuration of the
+ synthesized audio.
+ enable_time_pointing (Sequence[google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType]):
+ Whether and what timepoints are returned in
+ the response.
+ """
+
+ class TimepointType(proto.Enum):
+ r"""The type of timepoint information that is returned in the
+ response.
+ """
+ TIMEPOINT_TYPE_UNSPECIFIED = 0
+ SSML_MARK = 1
+
+ input = proto.Field(
+ proto.MESSAGE,
+ number=1,
+ message="SynthesisInput",
+ )
+ voice = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message="VoiceSelectionParams",
+ )
+ audio_config = proto.Field(
+ proto.MESSAGE,
+ number=3,
+ message="AudioConfig",
+ )
+ enable_time_pointing = proto.RepeatedField(
+ proto.ENUM,
+ number=4,
+ enum=TimepointType,
+ )
+
+
+class SynthesisInput(proto.Message):
+ r"""Contains text input to be synthesized. Either ``text`` or ``ssml``
+ must be supplied. Supplying both or neither returns
+ [google.rpc.Code.INVALID_ARGUMENT][]. The input size is limited to
+ 5000 characters.
+
+ 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:
+ text (str):
+ The raw text to be synthesized.
+
+ This field is a member of `oneof`_ ``input_source``.
+ ssml (str):
+ The SSML document to be synthesized. The SSML document must
+ be valid and well-formed. Otherwise the RPC will fail and
+ return [google.rpc.Code.INVALID_ARGUMENT][]. For more
+ information, see
+ `SSML `__.
+
+ This field is a member of `oneof`_ ``input_source``.
+ """
+
+ text = proto.Field(
+ proto.STRING,
+ number=1,
+ oneof="input_source",
+ )
+ ssml = proto.Field(
+ proto.STRING,
+ number=2,
+ oneof="input_source",
+ )
+
+
+class VoiceSelectionParams(proto.Message):
+ r"""Description of which voice to use for a synthesis request.
+
+ Attributes:
+ language_code (str):
+ Required. The language (and potentially also the region) of
+ the voice expressed as a
+ `BCP-47 `__
+ language tag, e.g. "en-US". This should not include a script
+ tag (e.g. use "cmn-cn" rather than "cmn-Hant-cn"), because
+ the script will be inferred from the input provided in the
+ SynthesisInput. The TTS service will use this parameter to
+ help choose an appropriate voice. Note that the TTS service
+ may choose a voice with a slightly different language code
+ than the one selected; it may substitute a different region
+ (e.g. using en-US rather than en-CA if there isn't a
+ Canadian voice available), or even a different language,
+ e.g. using "nb" (Norwegian Bokmal) instead of "no"
+ (Norwegian)".
+ name (str):
+ The name of the voice. If not set, the service will choose a
+ voice based on the other parameters such as language_code
+ and gender.
+ ssml_gender (google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender):
+ The preferred gender of the voice. If not set, the service
+ will choose a voice based on the other parameters such as
+ language_code and name. Note that this is only a preference,
+ not requirement; if a voice of the appropriate gender is not
+ available, the synthesizer should substitute a voice with a
+ different gender rather than failing the request.
+ custom_voice (google.cloud.texttospeech_v1beta1.types.CustomVoiceParams):
+ The configuration for a custom voice. If
+ [CustomVoiceParams.model] is set, the service will choose
+ the custom voice matching the specified configuration.
+ """
+
+ language_code = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ name = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+ ssml_gender = proto.Field(
+ proto.ENUM,
+ number=3,
+ enum="SsmlVoiceGender",
+ )
+ custom_voice = proto.Field(
+ proto.MESSAGE,
+ number=4,
+ message="CustomVoiceParams",
+ )
+
+
+class AudioConfig(proto.Message):
+ r"""Description of audio data to be synthesized.
+
+ Attributes:
+ audio_encoding (google.cloud.texttospeech_v1beta1.types.AudioEncoding):
+ Required. The format of the audio byte
+ stream.
+ speaking_rate (float):
+ Optional. Input only. Speaking rate/speed, in the range
+ [0.25, 4.0]. 1.0 is the normal native speed supported by the
+ specific voice. 2.0 is twice as fast, and 0.5 is half as
+ fast. If unset(0.0), defaults to the native 1.0 speed. Any
+ other values < 0.25 or > 4.0 will return an error.
+ pitch (float):
+ Optional. Input only. Speaking pitch, in the range [-20.0,
+ 20.0]. 20 means increase 20 semitones from the original
+ pitch. -20 means decrease 20 semitones from the original
+ pitch.
+ volume_gain_db (float):
+ Optional. Input only. Volume gain (in dB) of the normal
+ native volume supported by the specific voice, in the range
+ [-96.0, 16.0]. If unset, or set to a value of 0.0 (dB), will
+ play at normal native signal amplitude. A value of -6.0 (dB)
+ will play at approximately half the amplitude of the normal
+ native signal amplitude. A value of +6.0 (dB) will play at
+ approximately twice the amplitude of the normal native
+ signal amplitude. Strongly recommend not to exceed +10 (dB)
+ as there's usually no effective increase in loudness for any
+ value greater than that.
+ sample_rate_hertz (int):
+ Optional. The synthesis sample rate (in hertz) for this
+ audio. When this is specified in SynthesizeSpeechRequest, if
+ this is different from the voice's natural sample rate, then
+ the synthesizer will honor this request by converting to the
+ desired sample rate (which might result in worse audio
+ quality), unless the specified sample rate is not supported
+ for the encoding chosen, in which case it will fail the
+ request and return [google.rpc.Code.INVALID_ARGUMENT][].
+ effects_profile_id (Sequence[str]):
+ Optional. Input only. An identifier which selects 'audio
+ effects' profiles that are applied on (post synthesized)
+ text to speech. Effects are applied on top of each other in
+ the order they are given. See `audio
+ profiles `__
+ for current supported profile ids.
+ """
+
+ audio_encoding = proto.Field(
+ proto.ENUM,
+ number=1,
+ enum="AudioEncoding",
+ )
+ speaking_rate = proto.Field(
+ proto.DOUBLE,
+ number=2,
+ )
+ pitch = proto.Field(
+ proto.DOUBLE,
+ number=3,
+ )
+ volume_gain_db = proto.Field(
+ proto.DOUBLE,
+ number=4,
+ )
+ sample_rate_hertz = proto.Field(
+ proto.INT32,
+ number=5,
+ )
+ effects_profile_id = proto.RepeatedField(
+ proto.STRING,
+ number=6,
+ )
+
+
+class CustomVoiceParams(proto.Message):
+ r"""Description of the custom voice to be synthesized.
+
+ Attributes:
+ model (str):
+ Required. The name of the AutoML model that
+ synthesizes the custom voice.
+ reported_usage (google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage):
+ Optional. The usage of the synthesized audio
+ to be reported.
+ """
+
+ class ReportedUsage(proto.Enum):
+ r"""The usage of the synthesized audio. You must report your
+ honest and correct usage of the service as it's regulated by
+ contract and will cause significant difference in billing.
+ """
+ REPORTED_USAGE_UNSPECIFIED = 0
+ REALTIME = 1
+ OFFLINE = 2
+
+ model = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ reported_usage = proto.Field(
+ proto.ENUM,
+ number=3,
+ enum=ReportedUsage,
+ )
+
+
+class SynthesizeSpeechResponse(proto.Message):
+ r"""The message returned to the client by the ``SynthesizeSpeech``
+ method.
+
+ Attributes:
+ audio_content (bytes):
+ The audio data bytes encoded as specified in the request,
+ including the header for encodings that are wrapped in
+ containers (e.g. MP3, OGG_OPUS). For LINEAR16 audio, we
+ include the WAV header. Note: as with all bytes fields,
+ protobuffers use a pure binary representation, whereas JSON
+ representations use base64.
+ timepoints (Sequence[google.cloud.texttospeech_v1beta1.types.Timepoint]):
+ A link between a position in the original request input and
+ a corresponding time in the output audio. It's only
+ supported via ```` of SSML input.
+ audio_config (google.cloud.texttospeech_v1beta1.types.AudioConfig):
+ The audio metadata of ``audio_content``.
+ """
+
+ audio_content = proto.Field(
+ proto.BYTES,
+ number=1,
+ )
+ timepoints = proto.RepeatedField(
+ proto.MESSAGE,
+ number=2,
+ message="Timepoint",
+ )
+ audio_config = proto.Field(
+ proto.MESSAGE,
+ number=4,
+ message="AudioConfig",
+ )
+
+
+class Timepoint(proto.Message):
+ r"""This contains a mapping between a certain point in the input
+ text and a corresponding time in the output audio.
+
+ Attributes:
+ mark_name (str):
+ Timepoint name as received from the client within ````
+ tag.
+ time_seconds (float):
+ Time offset in seconds from the start of the
+ synthesized audio.
+ """
+
+ mark_name = proto.Field(
+ proto.STRING,
+ number=4,
+ )
+ time_seconds = proto.Field(
+ proto.DOUBLE,
+ number=3,
+ )
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/decrypt-secrets.sh b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/decrypt-secrets.sh
new file mode 100755
index 000000000000..21f6d2a26d90
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/decrypt-secrets.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+ROOT=$( dirname "$DIR" )
+
+# Work from the project root.
+cd $ROOT
+
+# Prevent it from overriding files.
+# We recommend that sample authors use their own service account files and cloud project.
+# In that case, they are supposed to prepare these files by themselves.
+if [[ -f "testing/test-env.sh" ]] || \
+ [[ -f "testing/service-account.json" ]] || \
+ [[ -f "testing/client-secrets.json" ]]; then
+ echo "One or more target files exist, aborting."
+ exit 1
+fi
+
+# Use SECRET_MANAGER_PROJECT if set, fallback to cloud-devrel-kokoro-resources.
+PROJECT_ID="${SECRET_MANAGER_PROJECT:-cloud-devrel-kokoro-resources}"
+
+gcloud secrets versions access latest --secret="python-docs-samples-test-env" \
+ --project="${PROJECT_ID}" \
+ > testing/test-env.sh
+gcloud secrets versions access latest \
+ --secret="python-docs-samples-service-account" \
+ --project="${PROJECT_ID}" \
+ > testing/service-account.json
+gcloud secrets versions access latest \
+ --secret="python-docs-samples-client-secrets" \
+ --project="${PROJECT_ID}" \
+ > testing/client-secrets.json
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_keywords.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_keywords.py
new file mode 100644
index 000000000000..c216d0bad6d9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_keywords.py
@@ -0,0 +1,178 @@
+# -*- coding: utf-8 -*-
+
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import argparse
+import os
+import libcst as cst
+import pathlib
+import sys
+from typing import (Any, Callable, Dict, List, Sequence, Tuple)
+
+
+def partition(
+ predicate: Callable[[Any], bool],
+ iterator: Sequence[Any]
+) -> Tuple[List[Any], List[Any]]:
+ """A stable, out-of-place partition."""
+ results = ([], [])
+
+ for i in iterator:
+ results[int(predicate(i))].append(i)
+
+ # Returns trueList, falseList
+ return results[1], results[0]
+
+
+class texttospeechCallTransformer(cst.CSTTransformer):
+ CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata')
+ METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
+ 'list_voices': ('language_code', ),
+ 'synthesize_speech': ('input', 'voice', 'audio_config', ),
+ }
+
+ def leave_Call(self, original: cst.Call, updated: cst.Call) -> cst.CSTNode:
+ try:
+ key = original.func.attr.value
+ kword_params = self.METHOD_TO_PARAMS[key]
+ except (AttributeError, KeyError):
+ # Either not a method from the API or too convoluted to be sure.
+ return updated
+
+ # If the existing code is valid, keyword args come after positional args.
+ # Therefore, all positional args must map to the first parameters.
+ args, kwargs = partition(lambda a: not bool(a.keyword), updated.args)
+ if any(k.keyword.value == "request" for k in kwargs):
+ # We've already fixed this file, don't fix it again.
+ return updated
+
+ kwargs, ctrl_kwargs = partition(
+ lambda a: not a.keyword.value in self.CTRL_PARAMS,
+ kwargs
+ )
+
+ args, ctrl_args = args[:len(kword_params)], args[len(kword_params):]
+ ctrl_kwargs.extend(cst.Arg(value=a.value, keyword=cst.Name(value=ctrl))
+ for a, ctrl in zip(ctrl_args, self.CTRL_PARAMS))
+
+ request_arg = cst.Arg(
+ value=cst.Dict([
+ cst.DictElement(
+ cst.SimpleString("'{}'".format(name)),
+ cst.Element(value=arg.value)
+ )
+ # Note: the args + kwargs looks silly, but keep in mind that
+ # the control parameters had to be stripped out, and that
+ # those could have been passed positionally or by keyword.
+ for name, arg in zip(kword_params, args + kwargs)]),
+ keyword=cst.Name("request")
+ )
+
+ return updated.with_changes(
+ args=[request_arg] + ctrl_kwargs
+ )
+
+
+def fix_files(
+ in_dir: pathlib.Path,
+ out_dir: pathlib.Path,
+ *,
+ transformer=texttospeechCallTransformer(),
+):
+ """Duplicate the input dir to the output dir, fixing file method calls.
+
+ Preconditions:
+ * in_dir is a real directory
+ * out_dir is a real, empty directory
+ """
+ pyfile_gen = (
+ pathlib.Path(os.path.join(root, f))
+ for root, _, files in os.walk(in_dir)
+ for f in files if os.path.splitext(f)[1] == ".py"
+ )
+
+ for fpath in pyfile_gen:
+ with open(fpath, 'r') as f:
+ src = f.read()
+
+ # Parse the code and insert method call fixes.
+ tree = cst.parse_module(src)
+ updated = tree.visit(transformer)
+
+ # Create the path and directory structure for the new file.
+ updated_path = out_dir.joinpath(fpath.relative_to(in_dir))
+ updated_path.parent.mkdir(parents=True, exist_ok=True)
+
+ # Generate the updated source file at the corresponding path.
+ with open(updated_path, 'w') as f:
+ f.write(updated.code)
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description="""Fix up source that uses the texttospeech client library.
+
+The existing sources are NOT overwritten but are copied to output_dir with changes made.
+
+Note: This tool operates at a best-effort level at converting positional
+ parameters in client method calls to keyword based parameters.
+ Cases where it WILL FAIL include
+ A) * or ** expansion in a method call.
+ B) Calls via function or method alias (includes free function calls)
+ C) Indirect or dispatched calls (e.g. the method is looked up dynamically)
+
+ These all constitute false negatives. The tool will also detect false
+ positives when an API method shares a name with another method.
+""")
+ parser.add_argument(
+ '-d',
+ '--input-directory',
+ required=True,
+ dest='input_dir',
+ help='the input directory to walk for python files to fix up',
+ )
+ parser.add_argument(
+ '-o',
+ '--output-directory',
+ required=True,
+ dest='output_dir',
+ help='the directory to output files fixed via un-flattening',
+ )
+ args = parser.parse_args()
+ input_dir = pathlib.Path(args.input_dir)
+ output_dir = pathlib.Path(args.output_dir)
+ if not input_dir.is_dir():
+ print(
+ f"input directory '{input_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if not output_dir.is_dir():
+ print(
+ f"output directory '{output_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if os.listdir(output_dir):
+ print(
+ f"output directory '{output_dir}' is not empty",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ fix_files(input_dir, output_dir)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_texttospeech_v1_keywords.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_texttospeech_v1_keywords.py
new file mode 100644
index 000000000000..22feca289b87
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_texttospeech_v1_keywords.py
@@ -0,0 +1,177 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import argparse
+import os
+import libcst as cst
+import pathlib
+import sys
+from typing import (Any, Callable, Dict, List, Sequence, Tuple)
+
+
+def partition(
+ predicate: Callable[[Any], bool],
+ iterator: Sequence[Any]
+) -> Tuple[List[Any], List[Any]]:
+ """A stable, out-of-place partition."""
+ results = ([], [])
+
+ for i in iterator:
+ results[int(predicate(i))].append(i)
+
+ # Returns trueList, falseList
+ return results[1], results[0]
+
+
+class texttospeechCallTransformer(cst.CSTTransformer):
+ CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata')
+ METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
+ 'list_voices': ('language_code', ),
+ 'synthesize_speech': ('input', 'voice', 'audio_config', ),
+ }
+
+ def leave_Call(self, original: cst.Call, updated: cst.Call) -> cst.CSTNode:
+ try:
+ key = original.func.attr.value
+ kword_params = self.METHOD_TO_PARAMS[key]
+ except (AttributeError, KeyError):
+ # Either not a method from the API or too convoluted to be sure.
+ return updated
+
+ # If the existing code is valid, keyword args come after positional args.
+ # Therefore, all positional args must map to the first parameters.
+ args, kwargs = partition(lambda a: not bool(a.keyword), updated.args)
+ if any(k.keyword.value == "request" for k in kwargs):
+ # We've already fixed this file, don't fix it again.
+ return updated
+
+ kwargs, ctrl_kwargs = partition(
+ lambda a: a.keyword.value not in self.CTRL_PARAMS,
+ kwargs
+ )
+
+ args, ctrl_args = args[:len(kword_params)], args[len(kword_params):]
+ ctrl_kwargs.extend(cst.Arg(value=a.value, keyword=cst.Name(value=ctrl))
+ for a, ctrl in zip(ctrl_args, self.CTRL_PARAMS))
+
+ request_arg = cst.Arg(
+ value=cst.Dict([
+ cst.DictElement(
+ cst.SimpleString("'{}'".format(name)),
+cst.Element(value=arg.value)
+ )
+ # Note: the args + kwargs looks silly, but keep in mind that
+ # the control parameters had to be stripped out, and that
+ # those could have been passed positionally or by keyword.
+ for name, arg in zip(kword_params, args + kwargs)]),
+ keyword=cst.Name("request")
+ )
+
+ return updated.with_changes(
+ args=[request_arg] + ctrl_kwargs
+ )
+
+
+def fix_files(
+ in_dir: pathlib.Path,
+ out_dir: pathlib.Path,
+ *,
+ transformer=texttospeechCallTransformer(),
+):
+ """Duplicate the input dir to the output dir, fixing file method calls.
+
+ Preconditions:
+ * in_dir is a real directory
+ * out_dir is a real, empty directory
+ """
+ pyfile_gen = (
+ pathlib.Path(os.path.join(root, f))
+ for root, _, files in os.walk(in_dir)
+ for f in files if os.path.splitext(f)[1] == ".py"
+ )
+
+ for fpath in pyfile_gen:
+ with open(fpath, 'r') as f:
+ src = f.read()
+
+ # Parse the code and insert method call fixes.
+ tree = cst.parse_module(src)
+ updated = tree.visit(transformer)
+
+ # Create the path and directory structure for the new file.
+ updated_path = out_dir.joinpath(fpath.relative_to(in_dir))
+ updated_path.parent.mkdir(parents=True, exist_ok=True)
+
+ # Generate the updated source file at the corresponding path.
+ with open(updated_path, 'w') as f:
+ f.write(updated.code)
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description="""Fix up source that uses the texttospeech client library.
+
+The existing sources are NOT overwritten but are copied to output_dir with changes made.
+
+Note: This tool operates at a best-effort level at converting positional
+ parameters in client method calls to keyword based parameters.
+ Cases where it WILL FAIL include
+ A) * or ** expansion in a method call.
+ B) Calls via function or method alias (includes free function calls)
+ C) Indirect or dispatched calls (e.g. the method is looked up dynamically)
+
+ These all constitute false negatives. The tool will also detect false
+ positives when an API method shares a name with another method.
+""")
+ parser.add_argument(
+ '-d',
+ '--input-directory',
+ required=True,
+ dest='input_dir',
+ help='the input directory to walk for python files to fix up',
+ )
+ parser.add_argument(
+ '-o',
+ '--output-directory',
+ required=True,
+ dest='output_dir',
+ help='the directory to output files fixed via un-flattening',
+ )
+ args = parser.parse_args()
+ input_dir = pathlib.Path(args.input_dir)
+ output_dir = pathlib.Path(args.output_dir)
+ if not input_dir.is_dir():
+ print(
+ f"input directory '{input_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if not output_dir.is_dir():
+ print(
+ f"output directory '{output_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if os.listdir(output_dir):
+ print(
+ f"output directory '{output_dir}' is not empty",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ fix_files(input_dir, output_dir)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_texttospeech_v1beta1_keywords.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_texttospeech_v1beta1_keywords.py
new file mode 100644
index 000000000000..51094d944153
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/fixup_texttospeech_v1beta1_keywords.py
@@ -0,0 +1,177 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import argparse
+import os
+import libcst as cst
+import pathlib
+import sys
+from typing import (Any, Callable, Dict, List, Sequence, Tuple)
+
+
+def partition(
+ predicate: Callable[[Any], bool],
+ iterator: Sequence[Any]
+) -> Tuple[List[Any], List[Any]]:
+ """A stable, out-of-place partition."""
+ results = ([], [])
+
+ for i in iterator:
+ results[int(predicate(i))].append(i)
+
+ # Returns trueList, falseList
+ return results[1], results[0]
+
+
+class texttospeechCallTransformer(cst.CSTTransformer):
+ CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata')
+ METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
+ 'list_voices': ('language_code', ),
+ 'synthesize_speech': ('input', 'voice', 'audio_config', 'enable_time_pointing', ),
+ }
+
+ def leave_Call(self, original: cst.Call, updated: cst.Call) -> cst.CSTNode:
+ try:
+ key = original.func.attr.value
+ kword_params = self.METHOD_TO_PARAMS[key]
+ except (AttributeError, KeyError):
+ # Either not a method from the API or too convoluted to be sure.
+ return updated
+
+ # If the existing code is valid, keyword args come after positional args.
+ # Therefore, all positional args must map to the first parameters.
+ args, kwargs = partition(lambda a: not bool(a.keyword), updated.args)
+ if any(k.keyword.value == "request" for k in kwargs):
+ # We've already fixed this file, don't fix it again.
+ return updated
+
+ kwargs, ctrl_kwargs = partition(
+ lambda a: a.keyword.value not in self.CTRL_PARAMS,
+ kwargs
+ )
+
+ args, ctrl_args = args[:len(kword_params)], args[len(kword_params):]
+ ctrl_kwargs.extend(cst.Arg(value=a.value, keyword=cst.Name(value=ctrl))
+ for a, ctrl in zip(ctrl_args, self.CTRL_PARAMS))
+
+ request_arg = cst.Arg(
+ value=cst.Dict([
+ cst.DictElement(
+ cst.SimpleString("'{}'".format(name)),
+cst.Element(value=arg.value)
+ )
+ # Note: the args + kwargs looks silly, but keep in mind that
+ # the control parameters had to be stripped out, and that
+ # those could have been passed positionally or by keyword.
+ for name, arg in zip(kword_params, args + kwargs)]),
+ keyword=cst.Name("request")
+ )
+
+ return updated.with_changes(
+ args=[request_arg] + ctrl_kwargs
+ )
+
+
+def fix_files(
+ in_dir: pathlib.Path,
+ out_dir: pathlib.Path,
+ *,
+ transformer=texttospeechCallTransformer(),
+):
+ """Duplicate the input dir to the output dir, fixing file method calls.
+
+ Preconditions:
+ * in_dir is a real directory
+ * out_dir is a real, empty directory
+ """
+ pyfile_gen = (
+ pathlib.Path(os.path.join(root, f))
+ for root, _, files in os.walk(in_dir)
+ for f in files if os.path.splitext(f)[1] == ".py"
+ )
+
+ for fpath in pyfile_gen:
+ with open(fpath, 'r') as f:
+ src = f.read()
+
+ # Parse the code and insert method call fixes.
+ tree = cst.parse_module(src)
+ updated = tree.visit(transformer)
+
+ # Create the path and directory structure for the new file.
+ updated_path = out_dir.joinpath(fpath.relative_to(in_dir))
+ updated_path.parent.mkdir(parents=True, exist_ok=True)
+
+ # Generate the updated source file at the corresponding path.
+ with open(updated_path, 'w') as f:
+ f.write(updated.code)
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description="""Fix up source that uses the texttospeech client library.
+
+The existing sources are NOT overwritten but are copied to output_dir with changes made.
+
+Note: This tool operates at a best-effort level at converting positional
+ parameters in client method calls to keyword based parameters.
+ Cases where it WILL FAIL include
+ A) * or ** expansion in a method call.
+ B) Calls via function or method alias (includes free function calls)
+ C) Indirect or dispatched calls (e.g. the method is looked up dynamically)
+
+ These all constitute false negatives. The tool will also detect false
+ positives when an API method shares a name with another method.
+""")
+ parser.add_argument(
+ '-d',
+ '--input-directory',
+ required=True,
+ dest='input_dir',
+ help='the input directory to walk for python files to fix up',
+ )
+ parser.add_argument(
+ '-o',
+ '--output-directory',
+ required=True,
+ dest='output_dir',
+ help='the directory to output files fixed via un-flattening',
+ )
+ args = parser.parse_args()
+ input_dir = pathlib.Path(args.input_dir)
+ output_dir = pathlib.Path(args.output_dir)
+ if not input_dir.is_dir():
+ print(
+ f"input directory '{input_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if not output_dir.is_dir():
+ print(
+ f"output directory '{output_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if os.listdir(output_dir):
+ print(
+ f"output directory '{output_dir}' is not empty",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ fix_files(input_dir, output_dir)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/readme_gen.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/readme_gen.py
new file mode 100644
index 000000000000..91b59676bfc7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/readme_gen.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+
+# Copyright 2016 Google Inc
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Generates READMEs using configuration defined in yaml."""
+
+import argparse
+import io
+import os
+import subprocess
+
+import jinja2
+import yaml
+
+
+jinja_env = jinja2.Environment(
+ trim_blocks=True,
+ loader=jinja2.FileSystemLoader(
+ os.path.abspath(os.path.join(os.path.dirname(__file__), "templates"))
+ ),
+ autoescape=True,
+)
+
+README_TMPL = jinja_env.get_template('README.tmpl.rst')
+
+
+def get_help(file):
+ return subprocess.check_output(['python', file, '--help']).decode()
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument('source')
+ parser.add_argument('--destination', default='README.rst')
+
+ args = parser.parse_args()
+
+ source = os.path.abspath(args.source)
+ root = os.path.dirname(source)
+ destination = os.path.join(root, args.destination)
+
+ jinja_env.globals['get_help'] = get_help
+
+ with io.open(source, 'r') as f:
+ config = yaml.load(f)
+
+ # This allows get_help to execute in the right directory.
+ os.chdir(root)
+
+ output = README_TMPL.render(config)
+
+ with io.open(destination, 'w') as f:
+ f.write(output)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/README.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/README.tmpl.rst
new file mode 100644
index 000000000000..4fd239765b0a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/README.tmpl.rst
@@ -0,0 +1,87 @@
+{# The following line is a lie. BUT! Once jinja2 is done with it, it will
+ become truth! #}
+.. This file is automatically generated. Do not edit this file directly.
+
+{{product.name}} Python Samples
+===============================================================================
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+ :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/README.rst
+
+
+This directory contains samples for {{product.name}}. {{product.description}}
+
+{{description}}
+
+.. _{{product.name}}: {{product.url}}
+
+{% if required_api_url %}
+To run the sample, you need to enable the API at: {{required_api_url}}
+{% endif %}
+
+{% if required_role %}
+To run the sample, you need to have `{{required_role}}` role.
+{% endif %}
+
+{{other_required_steps}}
+
+{% if setup %}
+Setup
+-------------------------------------------------------------------------------
+
+{% for section in setup %}
+
+{% include section + '.tmpl.rst' %}
+
+{% endfor %}
+{% endif %}
+
+{% if samples %}
+Samples
+-------------------------------------------------------------------------------
+
+{% for sample in samples %}
+{{sample.name}}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+{% if not sample.hide_cloudshell_button %}
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+ :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/{{sample.file}},{{folder}}/README.rst
+{% endif %}
+
+
+{{sample.description}}
+
+To run this sample:
+
+.. code-block:: bash
+
+ $ python {{sample.file}}
+{% if sample.show_help %}
+
+ {{get_help(sample.file)|indent}}
+{% endif %}
+
+
+{% endfor %}
+{% endif %}
+
+{% if cloud_client_library %}
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source`_ and `report issues`_.
+
+.. _Google Cloud Client Library for Python:
+ https://googlecloudplatform.github.io/google-cloud-python/
+.. _browse the source:
+ https://github.com/GoogleCloudPlatform/google-cloud-python
+.. _report issues:
+ https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+{% endif %}
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/auth.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/auth.tmpl.rst
new file mode 100644
index 000000000000..1446b94a5e3a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/auth.tmpl.rst
@@ -0,0 +1,9 @@
+Authentication
+++++++++++++++
+
+This sample requires you to have authentication setup. Refer to the
+`Authentication Getting Started Guide`_ for instructions on setting up
+credentials for applications.
+
+.. _Authentication Getting Started Guide:
+ https://cloud.google.com/docs/authentication/getting-started
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/auth_api_key.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/auth_api_key.tmpl.rst
new file mode 100644
index 000000000000..11957ce2714a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/auth_api_key.tmpl.rst
@@ -0,0 +1,14 @@
+Authentication
+++++++++++++++
+
+Authentication for this service is done via an `API Key`_. To obtain an API
+Key:
+
+1. Open the `Cloud Platform Console`_
+2. Make sure that billing is enabled for your project.
+3. From the **Credentials** page, create a new **API Key** or use an existing
+ one for your project.
+
+.. _API Key:
+ https://developers.google.com/api-client-library/python/guide/aaa_apikeys
+.. _Cloud Console: https://console.cloud.google.com/project?_
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/install_deps.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/install_deps.tmpl.rst
new file mode 100644
index 000000000000..6f069c6c87a5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/install_deps.tmpl.rst
@@ -0,0 +1,29 @@
+Install Dependencies
+++++++++++++++++++++
+
+#. Clone python-docs-samples and change directory to the sample directory you want to use.
+
+ .. code-block:: bash
+
+ $ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions.
+
+ .. _Python Development Environment Setup Guide:
+ https://cloud.google.com/python/setup
+
+#. Create a virtualenv. Samples are compatible with Python 3.7+.
+
+ .. code-block:: bash
+
+ $ virtualenv env
+ $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+ .. code-block:: bash
+
+ $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/install_portaudio.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/install_portaudio.tmpl.rst
new file mode 100644
index 000000000000..5ea33d18c00c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/scripts/readme-gen/templates/install_portaudio.tmpl.rst
@@ -0,0 +1,35 @@
+Install PortAudio
++++++++++++++++++
+
+Install `PortAudio`_. This is required by the `PyAudio`_ library to stream
+audio from your computer's microphone. PyAudio depends on PortAudio for cross-platform compatibility, and is installed differently depending on the
+platform.
+
+* For Mac OS X, you can use `Homebrew`_::
+
+ brew install portaudio
+
+ **Note**: if you encounter an error when running `pip install` that indicates
+ it can't find `portaudio.h`, try running `pip install` with the following
+ flags::
+
+ pip install --global-option='build_ext' \
+ --global-option='-I/usr/local/include' \
+ --global-option='-L/usr/local/lib' \
+ pyaudio
+
+* For Debian / Ubuntu Linux::
+
+ apt-get install portaudio19-dev python-all-dev
+
+* Windows may work without having to install PortAudio explicitly (it will get
+ installed with PyAudio).
+
+For more details, see the `PyAudio installation`_ page.
+
+
+.. _PyAudio: https://people.csail.mit.edu/hubert/pyaudio/
+.. _PortAudio: http://www.portaudio.com/
+.. _PyAudio installation:
+ https://people.csail.mit.edu/hubert/pyaudio/#downloads
+.. _Homebrew: http://brew.sh
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/setup.cfg b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/setup.cfg
new file mode 100644
index 000000000000..c3a2b39f6528
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/setup.cfg
@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Generated by synthtool. DO NOT EDIT!
+[bdist_wheel]
+universal = 1
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/setup.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/setup.py
new file mode 100644
index 000000000000..ff386677707e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-auto/setup.py
@@ -0,0 +1,104 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import io
+import os
+
+import setuptools
+
+# Package metadata.
+
+name = "google-cloud-texttospeech"
+description = "Google Cloud Text-to-Speech API client library"
+version = "2.12.3"
+# Should be one of:
+# 'Development Status :: 3 - Alpha'
+# 'Development Status :: 4 - Beta'
+# 'Development Status :: 5 - Production/Stable'
+release_status = "Development Status :: 5 - Production/Stable"
+dependencies = [
+ "google-api-core[grpc] >= 1.32.0, <3.0.0dev,!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*",
+ "proto-plus >= 1.22.0, <2.0.0dev",
+ "protobuf>=3.19.5,<5.0.0dev,!=3.20.0,!=3.20.1,!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5",
+]
+extras = {}
+
+
+# Setup boilerplate below this line.
+
+package_root = os.path.abspath(os.path.dirname(__file__))
+
+readme_filename = os.path.join(package_root, "README.rst")
+with io.open(readme_filename, encoding="utf-8") as readme_file:
+ readme = readme_file.read()
+
+# Only include packages under the 'google' namespace. Do not include tests,
+# benchmarks, etc.
+packages = [
+ package
+ for package in setuptools.PEP420PackageFinder.find()
+ if package.startswith("google")
+]
+
+# Determine which namespaces are needed.
+namespaces = ["google"]
+if "google.cloud" in packages:
+ namespaces.append("google.cloud")
+
+
+setuptools.setup(
+ name=name,
+ version=version,
+ description=description,
+ long_description=readme,
+ author="Google LLC",
+ author_email="googleapis-packages@google.com",
+ license="Apache 2.0",
+ url="https://github.com/googleapis/python-texttospeech",
+ classifiers=[
+ release_status,
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: Apache Software License",
+ "Programming Language :: Python",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.7",
+ "Programming Language :: Python :: 3.8",
+ "Programming Language :: Python :: 3.9",
+ "Programming Language :: Python :: 3.10",
+ "Operating System :: OS Independent",
+ "Topic :: Internet",
+ ],
+ platforms="Posix; MacOS X; Windows",
+ packages=packages,
+ namespace_packages=namespaces,
+ install_requires=dependencies,
+ extras_require=extras,
+ python_requires=">=3.7",
+ scripts=["scripts/fixup_keywords.py"],
+ include_package_data=True,
+ zip_safe=False,
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/CHANGELOG.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/CHANGELOG.md
new file mode 100644
index 000000000000..76c13f4f41fa
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/CHANGELOG.md
@@ -0,0 +1,1149 @@
+# Changelog
+
+[PyPI History][1]
+
+[1]: https://pypi.org/project/google-cloud-pubsub/#history
+
+
+## [2.13.10](https://github.com/googleapis/python-pubsub/compare/v2.13.8...v2.13.10) (2022-10-14)
+
+
+### Bug Fixes
+
+* Batch at most 1,000 ack ids per request ([#802](https://github.com/googleapis/python-pubsub/issues/802)) ([4361e67](https://github.com/googleapis/python-pubsub/commit/4361e6735004a5600ee73979b99e6b9dd587c49b))
+* **deps:** Allow protobuf 3.19.5 ([#801](https://github.com/googleapis/python-pubsub/issues/801)) ([fa23503](https://github.com/googleapis/python-pubsub/commit/fa235033481783c2ec378b2a26b223bdff206461))
+* Silence invalid_ack_id warnings for receipt modacks ([#798](https://github.com/googleapis/python-pubsub/issues/798)) ([17feea5](https://github.com/googleapis/python-pubsub/commit/17feea5783f3a878b4dcfb3a8570585f7637378f))
+
+
+### Miscellaneous Chores
+
+* release as 2.13.10 ([34f022b](https://github.com/googleapis/python-pubsub/commit/34f022b4ee62d53a193bc2babafad508e2f2540b))
+
+## [2.13.8](https://github.com/googleapis/python-pubsub/compare/v2.13.7...v2.13.8) (2022-10-03)
+
+
+### Bug Fixes
+
+* **deps:** Require protobuf >= 3.20.2 ([#792](https://github.com/googleapis/python-pubsub/issues/792)) ([1a54f7c](https://github.com/googleapis/python-pubsub/commit/1a54f7cd3d997270e0a5d70f7caea32d8753be76))
+
+## [2.13.7](https://github.com/googleapis/python-pubsub/compare/v2.13.6...v2.13.7) (2022-09-22)
+
+
+### Bug Fixes
+
+* Remove expired ack_ids ([#787](https://github.com/googleapis/python-pubsub/issues/787)) ([b4b809d](https://github.com/googleapis/python-pubsub/commit/b4b809d616cf93881815d6baadf2dd322ab566d1))
+
+## [2.13.6](https://github.com/googleapis/python-pubsub/compare/v2.13.5...v2.13.6) (2022-08-11)
+
+
+### Bug Fixes
+
+* **deps:** allow protobuf < 5.0.0 ([#762](https://github.com/googleapis/python-pubsub/issues/762)) ([260bd18](https://github.com/googleapis/python-pubsub/commit/260bd183ffe19992be9a1c1d298438c1f44d3fa9))
+* **deps:** require proto-plus >= 1.22.0 ([260bd18](https://github.com/googleapis/python-pubsub/commit/260bd183ffe19992be9a1c1d298438c1f44d3fa9))
+* set stream_ack_deadline to max_duration_per_lease_extension or 60 s, set ack_deadline to min_duration_per_lease_extension or 10 s ([#760](https://github.com/googleapis/python-pubsub/issues/760)) ([4444129](https://github.com/googleapis/python-pubsub/commit/4444129b28a19296752e865b73827b78e99adea5))
+* Update stream_ack_deadline with ack_deadline ([#763](https://github.com/googleapis/python-pubsub/issues/763)) ([e600ad8](https://github.com/googleapis/python-pubsub/commit/e600ad8228930445765ffa0c45500a7779e25817))
+
+## [2.13.5](https://github.com/googleapis/python-pubsub/compare/v2.13.4...v2.13.5) (2022-08-10)
+
+
+### Documentation
+
+* reorganize sphinx structure ([#751](https://github.com/googleapis/python-pubsub/issues/751)) ([b6de574](https://github.com/googleapis/python-pubsub/commit/b6de57458a1976a068dd229208b9b678a9d3f866))
+
+## [2.13.4](https://github.com/googleapis/python-pubsub/compare/v2.13.3...v2.13.4) (2022-07-15)
+
+
+### Bug Fixes
+
+* Remove bidi modacks on StreamingPull initial request ([#738](https://github.com/googleapis/python-pubsub/issues/738)) ([1e7d469](https://github.com/googleapis/python-pubsub/commit/1e7d46901c4472a3534980621e88d81aa2e50760))
+
+## [2.13.3](https://github.com/googleapis/python-pubsub/compare/v2.13.2...v2.13.3) (2022-07-13)
+
+
+### Bug Fixes
+
+* **deps:** require google-api-core>=1.32.0,>=2.8.0 ([#735](https://github.com/googleapis/python-pubsub/issues/735)) ([a5624fb](https://github.com/googleapis/python-pubsub/commit/a5624fbee2951c7f0c3e413d7d399a41fa0aa4bf))
+
+## [2.13.2](https://github.com/googleapis/python-pubsub/compare/v2.13.1...v2.13.2) (2022-07-08)
+
+
+### Bug Fixes
+
+* **deps:** require google-api-core >= 2.8.0 ([#726](https://github.com/googleapis/python-pubsub/issues/726)) ([c80ad41](https://github.com/googleapis/python-pubsub/commit/c80ad41abf36c709f8299a6fa22f3672705b1b6d))
+
+## [2.13.1](https://github.com/googleapis/python-pubsub/compare/v2.13.0...v2.13.1) (2022-07-07)
+
+
+### Bug Fixes
+
+* change info logs to debug ([#693](https://github.com/googleapis/python-pubsub/issues/693)) ([950fbce](https://github.com/googleapis/python-pubsub/commit/950fbce009fd56a55feea971f8e6083fa84d54fc))
+* require python 3.7+ ([#730](https://github.com/googleapis/python-pubsub/issues/730)) ([0d949b8](https://github.com/googleapis/python-pubsub/commit/0d949b8da096d1b0a5e26f607b1cd79fb560252a))
+
+## [2.13.0](https://github.com/googleapis/python-pubsub/compare/v2.12.1...v2.13.0) (2022-06-06)
+
+
+### Features
+
+* add BigQuery configuration for subscriptions ([#685](https://github.com/googleapis/python-pubsub/issues/685)) ([6fa03be](https://github.com/googleapis/python-pubsub/commit/6fa03be779d6a7105bb7c029b95d4c357d2a49df))
+
+
+### Bug Fixes
+
+* add info log for bidi streaming pull ack_deadline requests ([#692](https://github.com/googleapis/python-pubsub/issues/692)) ([fcb67dd](https://github.com/googleapis/python-pubsub/commit/fcb67dd0d8fff5a583ebe0a3a08d0219601df8e9))
+* **deps:** require protobuf <4.0.0dev ([#699](https://github.com/googleapis/python-pubsub/issues/699)) ([dcdf013](https://github.com/googleapis/python-pubsub/commit/dcdf0137905949662ce191adcb6dd588bd74f9fe))
+
+
+### Documentation
+
+* fix changelog header to consistent size ([#700](https://github.com/googleapis/python-pubsub/issues/700)) ([93f2b62](https://github.com/googleapis/python-pubsub/commit/93f2b62a18f622d8da71043a6b6d3f53295db308))
+
+## [2.12.1](https://github.com/googleapis/python-pubsub/compare/v2.12.0...v2.12.1) (2022-05-11)
+
+
+### Bug Fixes
+
+* Add emulator support to schema service ([#658](https://github.com/googleapis/python-pubsub/issues/658)) ([1a07d7c](https://github.com/googleapis/python-pubsub/commit/1a07d7ce3b3580191f74b7895dd1b8afb13baccb))
+* Handle duplicate acks with streaming pull ([#662](https://github.com/googleapis/python-pubsub/issues/662)) ([219491e](https://github.com/googleapis/python-pubsub/commit/219491ea1e615f33e1955e3afc204a0281c525db))
+* set min snooze on lease management to .01 sec ([#678](https://github.com/googleapis/python-pubsub/issues/678)) ([91c6e69](https://github.com/googleapis/python-pubsub/commit/91c6e69e96953919bc86004692edd3a52c7b9796))
+
+
+### Documentation
+
+* fix project_path typo in UPGRADING.md ([#660](https://github.com/googleapis/python-pubsub/issues/660)) ([20d661c](https://github.com/googleapis/python-pubsub/commit/20d661c8562cc1f777ac7b3f1ba03dcad7a831c0))
+* mark eod as preview ([#657](https://github.com/googleapis/python-pubsub/issues/657)) ([418e1a3](https://github.com/googleapis/python-pubsub/commit/418e1a3783441469713ca8ec8776007ff0fdb15d))
+
+## [2.12.0](https://github.com/googleapis/python-pubsub/compare/v2.11.0...v2.12.0) (2022-04-06)
+
+
+### Features
+
+* increase GRPC max metadata size to 4 MB ([#623](https://github.com/googleapis/python-pubsub/issues/623)) ([54b9e07](https://github.com/googleapis/python-pubsub/commit/54b9e07401b7309f16ecfe2a7afc36ea69f24a9c))
+
+
+### Bug Fixes
+
+* mypy errors ([#622](https://github.com/googleapis/python-pubsub/issues/622)) ([dab13d5](https://github.com/googleapis/python-pubsub/commit/dab13d5fb1d723c971cd84ae20f18462e624a26d))
+* process ErrorInfo / GRPC errors for ack/modack only when exactly-once delivery is enabled ([#626](https://github.com/googleapis/python-pubsub/issues/626)) ([cc1953b](https://github.com/googleapis/python-pubsub/commit/cc1953bcf942fb394a92ba50ba615adf822bfe7d))
+
+## [2.11.0](https://github.com/googleapis/python-pubsub/compare/v2.10.0...v2.11.0) (2022-03-09)
+
+
+### Features
+
+* retry temporary GRPC statuses for ack/modack/nack when exactly-once delivery is enabled ([#607](https://github.com/googleapis/python-pubsub/issues/607)) ([a91bed8](https://github.com/googleapis/python-pubsub/commit/a91bed829c9040fcc6c1e70b99b66188ac4ded40))
+* return singleton success future for exactly-once methods in Message ([#608](https://github.com/googleapis/python-pubsub/issues/608)) ([253ced2](https://github.com/googleapis/python-pubsub/commit/253ced28f308450c7a1a93cc38f6d101ecd7d4c0))
+
+
+### Bug Fixes
+
+* **deps:** require google-api-core>=1.31.5, >=2.3.2 ([#600](https://github.com/googleapis/python-pubsub/issues/600)) ([1608b7f](https://github.com/googleapis/python-pubsub/commit/1608b7ffdd5b5db87e1e55fde763440ca9a4086e))
+* **deps:** require proto-plus>=1.15.0 ([1608b7f](https://github.com/googleapis/python-pubsub/commit/1608b7ffdd5b5db87e1e55fde763440ca9a4086e))
+
+## [2.10.0](https://github.com/googleapis/python-pubsub/compare/v2.9.0...v2.10.0) (2022-03-04)
+
+
+### Features
+
+* add api key support ([#571](https://github.com/googleapis/python-pubsub/issues/571)) ([cdda762](https://github.com/googleapis/python-pubsub/commit/cdda762f6d15d96f5e2d7fac975f3494dc49eaa9))
+* add exactly once delivery flag ([#577](https://github.com/googleapis/python-pubsub/issues/577)) ([d6614e2](https://github.com/googleapis/python-pubsub/commit/d6614e274328c58449e67dfc788e2e7986c0c10b))
+* add support for exactly once delivery ([#578](https://github.com/googleapis/python-pubsub/issues/578)) ([95a86fa](https://github.com/googleapis/python-pubsub/commit/95a86fa5f528701b760064f0cece0efa4e60cd44))
+* exactly-once delivery support ([#550](https://github.com/googleapis/python-pubsub/issues/550)) ([2fb6e15](https://github.com/googleapis/python-pubsub/commit/2fb6e1533192ae81dceee5c71283169a0a85a015))
+
+
+### Bug Fixes
+
+* **deps:** move libcst to extras ([#585](https://github.com/googleapis/python-pubsub/issues/585)) ([0846762](https://github.com/googleapis/python-pubsub/commit/084676243ca4afd54cda601e589b80883f9703a3))
+* refactor client classes for safer type checking ([#552](https://github.com/googleapis/python-pubsub/issues/552)) ([7f705be](https://github.com/googleapis/python-pubsub/commit/7f705beb927383f14b9d56f0341ee0de101f7c05))
+* resolve DuplicateCredentialArgs error when using credentials_file ([8ca8cf2](https://github.com/googleapis/python-pubsub/commit/8ca8cf27333baf823a1dffd081e63079f1a12625))
+
+
+### Samples
+* samples: create subscription with filtering enabled [#580](https://github.com/googleapis/python-pubsub/pull/580)
+* samples: handle empty response in sync pull samples [#586](https://github.com/googleapis/python-pubsub/pull/586)
+* samples: sample for receiving messages with exactly-once delivery enabled [#588](https://github.com/googleapis/python-pubsub/pull/588)
+* samples: create subscription with exactly once delivery [#592](https://github.com/googleapis/python-pubsub/pull/592)
+(https://github.com/googleapis/python-pubsub/pull/588
+
+
+### Documentation
+
+* add autogenerated code snippets ([aa3754c](https://github.com/googleapis/python-pubsub/commit/aa3754cf432bd02be2734a23a32d5b36cd216aee))
+* Docs have inconsistent default values for max_latency and max_bytes ([#572](https://github.com/googleapis/python-pubsub/issues/572)) ([d136dfd](https://github.com/googleapis/python-pubsub/commit/d136dfdb69ebeebd1411a1415f863b94d07078f0))
+
+## [2.9.0](https://www.github.com/googleapis/python-pubsub/compare/v2.8.0...v2.9.0) (2021-11-10)
+
+
+### Features
+
+* add context manager support in client ([#516](https://www.github.com/googleapis/python-pubsub/issues/516)) ([51eae67](https://www.github.com/googleapis/python-pubsub/commit/51eae67c47e2ce7d2f7620209e98df4a129801b5))
+* add support for Python 3.10 ([#518](https://www.github.com/googleapis/python-pubsub/issues/518)) ([bb25d75](https://www.github.com/googleapis/python-pubsub/commit/bb25d755d70ba19e69d8a281be65f13eb994967d))
+
+
+### Bug Fixes
+
+* add 'dict' annotation type to 'request' ([b72522a](https://www.github.com/googleapis/python-pubsub/commit/b72522a4617c4b2773fb6a5a631038791aa08300))
+* **deps:** drop packaging dependency ([290b9c5](https://www.github.com/googleapis/python-pubsub/commit/290b9c5615eaa03674b773a27b756483abd76195))
+* **deps:** require google-api-core >= 1.28.0 ([290b9c5](https://www.github.com/googleapis/python-pubsub/commit/290b9c5615eaa03674b773a27b756483abd76195))
+* improper types in pagers generation ([2ad639d](https://www.github.com/googleapis/python-pubsub/commit/2ad639d6370c7a085498595d7bd0d7eaadfff3c1))
+
+
+### Documentation
+
+* add type annotations to codebase ([#509](https://www.github.com/googleapis/python-pubsub/issues/509)) ([093cabf](https://www.github.com/googleapis/python-pubsub/commit/093cabff9f0464b1dfaa8f373b6fffbc439518de))
+* list oneofs in docstring ([290b9c5](https://www.github.com/googleapis/python-pubsub/commit/290b9c5615eaa03674b773a27b756483abd76195))
+
+## [2.8.0](https://www.github.com/googleapis/python-pubsub/compare/v2.7.1...v2.8.0) (2021-09-02)
+
+
+### Features
+
+* closed subscriber as context manager raises ([#488](https://www.github.com/googleapis/python-pubsub/issues/488)) ([a05a3f2](https://www.github.com/googleapis/python-pubsub/commit/a05a3f250cf8567ffe0d2eb3ecc45856a2bcd07c))
+
+
+### Documentation
+
+* clarify the types of Message parameters ([#486](https://www.github.com/googleapis/python-pubsub/issues/486)) ([633e91b](https://www.github.com/googleapis/python-pubsub/commit/633e91bbfc0a8f4f484089acff6812b754f40c75))
+
+## [2.7.1](https://www.github.com/googleapis/python-pubsub/compare/v2.7.0...v2.7.1) (2021-08-13)
+
+
+### Bug Fixes
+
+* remove dependency on pytz ([#472](https://www.github.com/googleapis/python-pubsub/issues/472)) ([972cc16](https://www.github.com/googleapis/python-pubsub/commit/972cc163f5a1477b37a5ab7e329faf1468637fa2))
+
+## [2.7.0](https://www.github.com/googleapis/python-pubsub/compare/v2.6.1...v2.7.0) (2021-07-24)
+
+
+### Features
+
+* Add `always_use_jwt_access`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+* Add method signature for `Subscriber.Pull` without the deprecated `return_immediately` field. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+* Add Pub/Sub topic retention fields. ([#456](https://www.github.com/googleapis/python-pubsub/issues/456)) ([911829d](https://www.github.com/googleapis/python-pubsub/commit/911829d85c6ec36a87b873cbfe34497b1a493dde))
+* Add subscription properties to streaming pull response. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+* Support self-signed JWT flow for service accounts. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+
+### Bug Fixes
+
+* Add async client to `%name_%version/init.py`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+* Disable `always_use_jwt_access`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+* Enable self signed JWT for gRPC. ([#458](https://www.github.com/googleapis/python-pubsub/issues/458)) ([c6e0ff6](https://www.github.com/googleapis/python-pubsub/commit/c6e0ff69faeda614aa6088af59d3420e16720d27))
+
+### Dependencies
+
+* Add `packaging` requirement. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+* Require `google-api-core >= 1.26.0`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+## 2.6.1
+
+07-05-2021 10:33 PDT
+
+### Dependencies
+
+- Fix possible crash by requiring `grpcio >= 1.38.1`. ([#414](https://github.com/googleapis/python-pubsub/issues/414)) ([7037a28](https://github.com/googleapis/python-pubsub/pull/435/commits/7037a28090aa4efa01808231721716bca80bb0b7))
+
+### Documentation
+
+- Adjust samples for publishing with error handler and flow control. ([#433](https://github.com/googleapis/python-pubsub/pull/433))
+
+### Internal / Testing Changes
+
+- Fix flaky sync pull sample test. ([#434](https://github.com/googleapis/python-pubsub/pull/434))
+- Mitigate flaky snippets tests. ([#432](https://github.com/googleapis/python-pubsub/pull/432))
+
+## [2.6.0](https://www.github.com/googleapis/python-pubsub/compare/v2.5.0...v2.6.0) (2021-06-17)
+
+
+### Features
+
+* support customizable retry and timeout settings on the publisher client ([#299](https://www.github.com/googleapis/python-pubsub/issues/299)) ([7597604](https://www.github.com/googleapis/python-pubsub/commit/7597604b41fa3a1e9bf34addc35c8647dde007cc))
+
+
+### Bug Fixes
+
+* ACK deadline set for received messages can be too low ([#416](https://www.github.com/googleapis/python-pubsub/issues/416)) ([e907f6e](https://www.github.com/googleapis/python-pubsub/commit/e907f6e05f59f64a3b08df3304e92ec960997be6))
+* threads can skip the line in publisher flow controller ([#422](https://www.github.com/googleapis/python-pubsub/issues/422)) ([ef89f55](https://www.github.com/googleapis/python-pubsub/commit/ef89f55a41044e9ad26b91132b4b1be9c7b2c127))
+
+
+### Documentation
+
+* block until the streaming pull shuts down ([#424](https://www.github.com/googleapis/python-pubsub/issues/424)) ([d0d0b70](https://www.github.com/googleapis/python-pubsub/commit/d0d0b704642df8dee893d3f585aeb666e19696fb))
+* explain that future.cancel() is non-blocking ([#420](https://www.github.com/googleapis/python-pubsub/issues/420)) ([c825789](https://www.github.com/googleapis/python-pubsub/commit/c825789bdff310f44cbb132a723e99d1e6331d8f))
+
+## [2.5.0](https://www.github.com/googleapis/python-pubsub/compare/v2.4.2...v2.5.0) (2021-05-18)
+
+
+### Features
+
+* Make publish futures compatible with `concurrent.futures.as_completed()`. ([#397](https://www.github.com/googleapis/python-pubsub/issues/397)) ([e29a2c0](https://www.github.com/googleapis/python-pubsub/commit/e29a2c0ac6c5d2ebf2311646e552a02f184cfedc))
+
+
+### Bug Fixes
+
+* Scheduler errors when executor in shutdown. ([#399](https://www.github.com/googleapis/python-pubsub/issues/399)) ([39a83d3](https://www.github.com/googleapis/python-pubsub/commit/39a83d3eef196e88478ad8362201a2ab12e9f681))
+
+## 2.4.2
+
+05-06-2021 23:50 PDT
+
+
+### Implementation Changes
+
+- Fix memory leak when publishing messages. ([#406](https://github.com/googleapis/python-pubsub/pull/406))
+- Do not crash if distribution cannot be found when extracting semantic version. ([#393](https://github.com/googleapis/python-pubsub/pull/393))
+- Emit a warning if `return_immediately` is set with synchronous pull. ([#355](https://github.com/googleapis/python-pubsub/pull/355))
+- Regenerate GAPIC layer with latest changes, use explicit default timeouts. ([#345](https://github.com/googleapis/python-pubsub/pull/345))
+
+
+### Documentation
+
+- Add additional info on `use_legacy_flow_control` parameter. ([#301](https://github.com/googleapis/python-pubsub/pull/301))
+- Remove EXPERIMENTAL tag for ordering keys in `publisher/client.py`. ([#324](https://github.com/googleapis/python-pubsub/pull/324))
+- Fix `create_topic()` call in README. ([#360](https://github.com/googleapis/python-pubsub/pull/360))
+- Generate PyPI token in secrets manager, fix spacing in docs (via synth). ([#384](https://github.com/googleapis/python-pubsub/pull/384))
+- Add `SECURITY.md`. ([#401](https://github.com/googleapis/python-pubsub/pull/401))
+
+
+### Internal / Testing Changes
+
+- Require 100% unit test coverage (via synth). ([#359](https://github.com/googleapis/python-pubsub/pull/359))
+- Bump test coverage to 100%. ([#364](https://github.com/googleapis/python-pubsub/pull/364))
+- Fix streaming pull close unit test flakiness. ([#361](https://github.com/googleapis/python-pubsub/pull/361))
+- Pass explicit credentials in all unit tests creating clients. ([#369](https://github.com/googleapis/python-pubsub/pull/369))
+- Fix flaky test for blocking pull shutdown. ([#378](https://github.com/googleapis/python-pubsub/pull/378))
+- Add missing licence header. ([#377](https://github.com/googleapis/python-pubsub/pull/377))
+
+## [2.4.1](https://www.github.com/googleapis/python-pubsub/compare/v2.4.0...v2.4.1) (2021-03-30)
+
+### Bug Fixes
+
+* Move `await_msg_callbacks` flag to `subscribe()` method, fixing a regression in Pub/Sub Lite client.
+ ([#320](https://www.github.com/googleapis/python-pubsub/issues/320)) ([d40d027](https://www.github.com/googleapis/python-pubsub/commit/d40d02713c8c189937ae5c21d099b88a3131a59f))
+* SSL error when using the client with the emulator. ([#297](https://www.github.com/googleapis/python-pubsub/issues/297)) ([83db672](https://www.github.com/googleapis/python-pubsub/commit/83db67239d3521457138699109f766d574a0a2c4))
+
+### Implementation Changes
+
+* (samples) Bump the max_time to 10 minutes for a flaky test. ([#311](https://www.github.com/googleapis/python-pubsub/issues/311)) ([e2678d4](https://www.github.com/googleapis/python-pubsub/commit/e2678d47c08e6b03782d2d744a4e630b933fdd51)), closes [#291](https://www.github.com/googleapis/python-pubsub/issues/291)
+* (samples) Mark delivery attempts test as flaky. ([#326](https://www.github.com/googleapis/python-pubsub/issues/326)) ([5a97ef1](https://www.github.com/googleapis/python-pubsub/commit/5a97ef1bb7512fe814a8f72a43b3e9698434cd8d))
+* (samples) Mitigate flakiness in subscriber_tests. ([#304](https://www.github.com/googleapis/python-pubsub/issues/304)) ([271a385](https://www.github.com/googleapis/python-pubsub/commit/271a3856d835967f18f6becdae5ad53d585d0ccf))
+* (samples) Retry `InternalServerError` in dead letter policy test. ([#329](https://www.github.com/googleapis/python-pubsub/issues/329)) ([34c9b11](https://www.github.com/googleapis/python-pubsub/commit/34c9b11ae697c280f32642c3101b7f7da971f589)), closes [#321](https://www.github.com/googleapis/python-pubsub/issues/321)
+
+### Documentation
+
+* Remove EXPERIMENTAL tag for ordering keys in `types.py`. ([#323](https://www.github.com/googleapis/python-pubsub/issues/323)) ([659cd7a](https://www.github.com/googleapis/python-pubsub/commit/659cd7ae2784245d4217fbc722dac04bd3222d32))
+* Remove EXPERIMENTAL tag from `Schema` service (via synth). ([#307](https://www.github.com/googleapis/python-pubsub/issues/307)) ([ad85202](https://www.github.com/googleapis/python-pubsub/commit/ad852028836520db779c5cc33689ffd7e5458a7d))
+
+
+## 2.4.0
+
+02-22-2021 05:02 PST
+
+
+### Implementation Changes
+
+### New Features
+
+- Add graceful streaming pull shutdown. ([#292](https://github.com/googleapis/python-pubsub/pull/292))
+
+### Documentation
+
+- Update samples with using the subscriber client as a context manager. ([#254](https://github.com/googleapis/python-pubsub/pull/254))
+
+## [2.3.0](https://www.github.com/googleapis/python-pubsub/compare/v2.2.0...v2.3.0) (2021-02-08)
+
+
+### Features
+
+* surface SchemaServiceClient in google.cloud.pubsub ([#281](https://www.github.com/googleapis/python-pubsub/issues/281)) ([8751bcc](https://www.github.com/googleapis/python-pubsub/commit/8751bcc5eb782df55769b48253629a3bde3d4661))
+
+
+### Bug Fixes
+
+* client version missing from the user agent header ([#275](https://www.github.com/googleapis/python-pubsub/issues/275)) ([b112f4f](https://www.github.com/googleapis/python-pubsub/commit/b112f4fcbf6f2bce8dcf37871bdc540b11f54fe3))
+* Don't open the google.cloud package by adding pubsub.py ([#269](https://www.github.com/googleapis/python-pubsub/issues/269)) ([542d79d](https://www.github.com/googleapis/python-pubsub/commit/542d79d7c5fb7403016150ba477485756cd4097b))
+* flaky samples tests ([#263](https://www.github.com/googleapis/python-pubsub/issues/263)) ([3d6a29d](https://www.github.com/googleapis/python-pubsub/commit/3d6a29de07cc09be663c90a3333f4cd33633994f))
+* Modify synth.py to update grpc transport options ([#266](https://www.github.com/googleapis/python-pubsub/issues/266)) ([41dcd30](https://www.github.com/googleapis/python-pubsub/commit/41dcd30636168f3dd1248f1d99170d531fc9bcb8))
+* pass anonymous credentials for emulator ([#250](https://www.github.com/googleapis/python-pubsub/issues/250)) ([8eed8e1](https://www.github.com/googleapis/python-pubsub/commit/8eed8e16019510dc8b20fb6b009d61a7ac532d26))
+* remove grpc send/recieve limits ([#259](https://www.github.com/googleapis/python-pubsub/issues/259)) ([fd2840c](https://www.github.com/googleapis/python-pubsub/commit/fd2840c10f92b03da7f4b40ac69c602220757c0a))
+
+## [2.2.0](https://www.github.com/googleapis/python-pubsub/compare/v2.1.0...v2.2.0) (2020-11-16)
+
+
+### Features
+
+* Add dead lettering max delivery attempts argument ([#236](https://www.github.com/googleapis/python-pubsub/issues/236)) ([7687ae5](https://www.github.com/googleapis/python-pubsub/commit/7687ae500bdb9c76e3ffb23302b4f32dc9627d81))
+* Enable server side flow control by default with the option to turn it off ([#231](https://www.github.com/googleapis/python-pubsub/issues/231)) ([94d738c](https://www.github.com/googleapis/python-pubsub/commit/94d738c07c6404a152c6729f5ba4b106b1fe9355))
+
+
+### Bug Fixes
+
+* fix mtls issue in handwritten layer ([#226](https://www.github.com/googleapis/python-pubsub/issues/226)) ([09a409c](https://www.github.com/googleapis/python-pubsub/commit/09a409c6240a74dcb46d8f3f86d4fb95a52274a7))
+* make fixup script consistent with migration docs ([#208](https://www.github.com/googleapis/python-pubsub/issues/208)) ([b64e218](https://www.github.com/googleapis/python-pubsub/commit/b64e2187ab0810437575580d6ddb5315ff60e274))
+
+
+### Documentation
+
+* document potentially unexpected blocking behavior of publish() method ([#214](https://www.github.com/googleapis/python-pubsub/issues/214)) ([b6d9bd7](https://www.github.com/googleapis/python-pubsub/commit/b6d9bd7c38d4fe597c25b7b5869fd4a1259c7687))
+* fix get topic_path in subscriber sample ([#210](https://www.github.com/googleapis/python-pubsub/issues/210)) ([7228f6c](https://www.github.com/googleapis/python-pubsub/commit/7228f6c9a4c050bf22bb4bc3582b89b04eaa8702))
+
+## 2.1.0
+
+09-21-2020 02:19 PDT
+
+
+### Implementation Changes
+
+- Convert all RPC error types to exceptions. ([#163](https://github.com/googleapis/python-pubsub/issues/163)) ([#170](https://github.com/googleapis/python-pubsub/pull/170))
+- Pass client options to publisher and subscriber clients. ([#166](https://github.com/googleapis/python-pubsub/issues/166)) ([#190](https://github.com/googleapis/python-pubsub/pull/190))
+
+
+### New Features
+
+- Regenerate the client lib to pick new mtls env (via synth). ([#197](https://github.com/googleapis/python-pubsub/pull/197))
+
+
+### Documentation
+
+- Add subscription detachment sample. ([#152](https://github.com/googleapis/python-pubsub/pull/152))
+- Use new call syntax in subscriber docs. ([#198](https://github.com/googleapis/python-pubsub/issues/198)) ([#203](https://github.com/googleapis/python-pubsub/pull/203))
+
+
+### Internal / Testing Changes
+
+- Update CODEOWNERS. ([#193](https://github.com/googleapis/python-pubsub/pull/193))
+
+## 2.0.0
+
+09-11-2020 05:03 PDT
+
+
+### Implementation Changes
+
+- Transition the library to microgenerator. ([#158](https://github.com/googleapis/python-pubsub/pull/158))
+ This is a **breaking change** that introduces several **method signature changes** and **drops support
+ for Python 2.7 and 3.5**.
+
+### Documentation
+
+- Add samples for using ordering keys. ([#156](https://github.com/googleapis/python-pubsub/pull/156))
+- Remove extra white space in delivery attempt sample. ([#159](https://github.com/googleapis/python-pubsub/pull/159))
+
+### Internal / Testing Changes
+
+- Fix flaky sequencer unit tests. ([#187](https://github.com/googleapis/python-pubsub/pull/187))
+
+## [1.7.0](https://www.github.com/googleapis/python-pubsub/compare/v1.6.1...v1.7.0) (2020-07-13)
+
+This is the last release that supports Python 2.7 and 3.5.
+
+### New Features
+
+- Add support for server-side flow control. ([#143](https://github.com/googleapis/python-pubsub/pull/143)) ([04e261c](https://www.github.com/googleapis/python-pubsub/commit/04e261c602a2919cc75b3efa3dab099fb2cf704c))
+
+### Dependencies
+
+- Update samples dependency `google-cloud-pubsub` to `v1.6.1`. ([#144](https://github.com/googleapis/python-pubsub/pull/144)) ([1cb6746](https://github.com/googleapis/python-pubsub/commit/1cb6746b00ebb23dbf1663bae301b32c3fc65a88))
+
+### Documentation
+
+- Add pubsub/cloud-client samples from the common samples repo (with commit history). ([#151](https://github.com/googleapis/python-pubsub/pull/151))
+- Add flow control section to publish overview. ([#129](https://github.com/googleapis/python-pubsub/pull/129)) ([acc19eb](https://www.github.com/googleapis/python-pubsub/commit/acc19eb048eef067d9818ef3e310b165d9c6307e))
+- Add a link to Pub/Sub filtering language public documentation to `pubsub.proto`. ([#121](https://github.com/googleapis/python-pubsub/pull/121)) ([8802d81](https://www.github.com/googleapis/python-pubsub/commit/8802d8126247f22e26057e68a42f5b5a82dcbf0d))
+
+
+## [1.6.1](https://www.github.com/googleapis/python-pubsub/compare/v1.6.0...v1.6.1) (2020-06-30)
+
+
+### Documentation
+
+* added Python2 sunset notice (synth) ([#140](https://www.github.com/googleapis/python-pubsub/issues/140)) ([c8f6378](https://www.github.com/googleapis/python-pubsub/commit/c8f63788636c2e3436c8ce6a01ef3b59e3df772a))
+* explain how to nack a sync pull message ([#123](https://www.github.com/googleapis/python-pubsub/issues/123)) ([f2eec65](https://www.github.com/googleapis/python-pubsub/commit/f2eec65cec43066ba7a2d1d45efa979e6b7add4f))
+
+## [1.6.0](https://www.github.com/googleapis/python-pubsub/compare/v1.5.0...v1.6.0) (2020-06-09)
+
+
+### Features
+
+* Add flow control for message publishing ([#96](https://www.github.com/googleapis/python-pubsub/issues/96)) ([06085c4](https://www.github.com/googleapis/python-pubsub/commit/06085c4083b9dccdd50383257799904510bbf3a0))
+
+
+### Bug Fixes
+
+* Fix PubSub incompatibility with api-core 1.17.0+ ([#103](https://www.github.com/googleapis/python-pubsub/issues/103)) ([c02060f](https://www.github.com/googleapis/python-pubsub/commit/c02060fbbe6e2ca4664bee08d2de10665d41dc0b))
+
+
+### Documentation
+- Clarify that Schedulers shouldn't be used with multiple SubscriberClients ([#100](https://github.com/googleapis/python-pubsub/pull/100)) ([cf9e87c](https://github.com/googleapis/python-pubsub/commit/cf9e87c80c0771f3fa6ef784a8d76cb760ad37ef))
+- Fix update subscription/snapshot/topic samples ([#113](https://github.com/googleapis/python-pubsub/pull/113)) ([e62c38b](https://github.com/googleapis/python-pubsub/commit/e62c38bb33de2434e32f866979de769382dea34a))
+
+
+### Internal / Testing Changes
+- Re-generated service implementaton using synth: removed experimental notes from the RetryPolicy and filtering features in anticipation of GA, added DetachSubscription (experimental) ([#114](https://github.com/googleapis/python-pubsub/pull/114)) ([0132a46](https://github.com/googleapis/python-pubsub/commit/0132a4680e0727ce45d5e27d98ffc9f3541a0962))
+- Incorporate will_accept() checks into publish() ([#108](https://github.com/googleapis/python-pubsub/pull/108)) ([6c7677e](https://github.com/googleapis/python-pubsub/commit/6c7677ecb259672bbb9b6f7646919e602c698570))
+
+## [1.5.0](https://www.github.com/googleapis/python-pubsub/compare/v1.4.3...v1.5.0) (2020-05-04)
+
+
+### Features
+
+* add methods for listing snapshots (via synth) ([#66](https://www.github.com/googleapis/python-pubsub/issues/66)) ([4ce898e](https://www.github.com/googleapis/python-pubsub/commit/4ce898e80eeb16b18d1ee29c678ade149804d186))
+* send client id with StreamingPullRequest ([#58](https://www.github.com/googleapis/python-pubsub/issues/58)) ([9f8acfa](https://www.github.com/googleapis/python-pubsub/commit/9f8acfacfbe93224f59439bb51a17fc28b06c22a)), closes [#62](https://www.github.com/googleapis/python-pubsub/issues/62)
+
+## [1.4.3](https://www.github.com/googleapis/python-pubsub/compare/v1.4.2...v1.4.3) (2020-04-16)
+
+
+### Bug Fixes
+
+* fix docs warnings in Sphinx 3.0+ ([#70](https://www.github.com/googleapis/python-pubsub/issues/70)) ([21e761e](https://www.github.com/googleapis/python-pubsub/commit/21e761ee89a4c03e105dc9cddbab0a34be9a9fda))
+* restrict api-core dependency to < 1.17.0 ([#76](https://www.github.com/googleapis/python-pubsub/issues/76)) ([191b051](https://www.github.com/googleapis/python-pubsub/commit/191b0516335f5c60828a818ba79e99d6c68aa7bd))
+
+## [1.4.2](https://www.github.com/googleapis/python-pubsub/compare/v1.4.1...v1.4.2) (2020-03-25)
+
+### Bug Fixes
+
+* update generated retry timings for publish and pull rpcs via synth ([#43](https://www.github.com/googleapis/python-pubsub/issues/43)) ([4f7fe85](https://www.github.com/googleapis/python-pubsub/commit/4f7fe85618d811fea94cb46b5dc758aa78c328a8))
+* use client_options.api_endpoint parameter instead of ignoring it ([#59](https://www.github.com/googleapis/python-pubsub/issues/59)) ([56b8d7b](https://www.github.com/googleapis/python-pubsub/commit/56b8d7b046a495ce2ce59bebdd354385147a5013)), closes [#61](https://www.github.com/googleapis/python-pubsub/issues/61)
+
+## [1.4.1](https://www.github.com/googleapis/python-pubsub/compare/v1.4.0...v1.4.1) (2020-03-23)
+
+### Bug Fixes
+
+* Don't assert on unordered publishes after publish error. ([#49](https://www.github.com/googleapis/python-pubsub/issues/49)) ([ea19ce6](https://www.github.com/googleapis/python-pubsub/commit/ea19ce616f6961e8993b72cd2921f7f3e61541f9))
+
+## [1.4.0](https://www.github.com/googleapis/python-pubsub/compare/v1.3.1...v1.4.0) (2020-03-06)
+
+### Features
+
+* **pubsub:** implement max_duration_per_lease_extension option ([#38](https://www.github.com/googleapis/python-pubsub/issues/38)) ([d911a2d](https://www.github.com/googleapis/python-pubsub/commit/d911a2dc8edf3c348ad3f128368b30e32dbc449e))
+
+## [1.3.1](https://www.github.com/googleapis/python-pubsub/compare/v1.3.0...v1.3.1) (2020-02-28)
+
+### Bug Fixes
+
+* shutdown error on streaming pull callback error ([#40](https://www.github.com/googleapis/python-pubsub/issues/40)) ([552539e](https://www.github.com/googleapis/python-pubsub/commit/552539e7beb30833c39dd29bfcb0183a07895f97))
+
+## [1.3.0](https://www.github.com/googleapis/python-pubsub/compare/v1.2.0...v1.3.0) (2020-02-20)
+
+### Features
+
+* **pubsub:** ordering keys ([#26](https://www.github.com/googleapis/python-pubsub/issues/26)) ([cc3093a](https://www.github.com/googleapis/python-pubsub/commit/cc3093a2c0304259bc374bc2eeec9630e4a11a5e))
+* add context manager capability to subscriber ([#32](https://www.github.com/googleapis/python-pubsub/issues/32)) ([b58d0d8](https://www.github.com/googleapis/python-pubsub/commit/b58d0d8e404c0a085b89d3407e6640651e81568c))
+
+## [1.2.0](https://www.github.com/googleapis/python-pubsub/compare/v1.1.0...v1.2.0) (2020-02-05)
+
+### Features
+
+* **pubsub:** add delivery attempt property to message object received by user code ([#10205](https://www.github.com/googleapis/google-cloud-python/issues/10205)) ([a0937c1](https://www.github.com/googleapis/python-pubsub/commit/a0937c13107b92271913de579b60f24b2aaac177))
+* add `StreamingPullRequest.client_id` field (via synth) ([199d56a](https://www.github.com/googleapis/python-pubsub/commit/199d56a939bb6244f67138f843dafdd80721f0d3))
+
+### Bug Fixes
+
+* **pubsub:** handle None in on response callback ([#9982](https://www.github.com/googleapis/google-cloud-python/issues/9982)) ([6596c4b](https://www.github.com/googleapis/python-pubsub/commit/6596c4bae5526d82f5c1b5e0c243b2883404d51f))
+* replace unsafe six.PY3 with PY2 for better future compatibility with Python 4 ([#10081](https://www.github.com/googleapis/google-cloud-python/issues/10081)) ([975c1ac](https://www.github.com/googleapis/python-pubsub/commit/975c1ac2cfdac0ce4403c0b56ad19f2ee7241f1a))
+
+## 1.1.0
+
+12-09-2019 18:51 PST
+
+### Implementation Changes
+- Update client configurations (via synth). ([#9784](https://github.com/googleapis/google-cloud-python/pull/9784))
+- Include request overhead when computing publish batch size overflow. ([#9911](https://github.com/googleapis/google-cloud-python/pull/9911))
+- Split large (mod)ACK requests into smaller ones. ([#9594](https://github.com/googleapis/google-cloud-python/pull/9594))
+- Fix messages delivered multiple times despite a long ACK deadline. ([#9525](https://github.com/googleapis/google-cloud-python/pull/9525))
+- Update batching and flow control parameters to be same as the other client libraries. ([#9597](https://github.com/googleapis/google-cloud-python/pull/9597))
+- Add `StreamingPullManager._should_terminate`. ([#9335](https://github.com/googleapis/google-cloud-python/pull/9335))
+
+### New Features
+- Add stop method. ([#9365](https://github.com/googleapis/google-cloud-python/pull/9365))
+
+### Dependencies
+- Add Python 2 sunset banner to documentation. ([#9036](https://github.com/googleapis/google-cloud-python/pull/9036))
+
+### Documentation
+- Change spacing in docs templates (via synth). ([#9759](https://github.com/googleapis/google-cloud-python/pull/9759))
+
+### Internal / Testing Changes
+- Refactor fake leaser test helper. ([#9632](https://github.com/googleapis/google-cloud-python/pull/9632))
+- Add subscriber role test for streaming. ([#9507](https://github.com/googleapis/google-cloud-python/pull/9507))
+
+## 1.0.2
+
+09-30-2019 11:57 PDT
+
+
+### Implementation Changes
+
+- Streaming pull shouldn't need `subscriptions.get` permission ([#9360](https://github.com/googleapis/google-cloud-python/pull/9360)).
+
+## 1.0.1
+
+09-27-2019 07:01 PDT
+
+
+### Implementation Changes
+- Set default stream ACK deadline to subscriptions'. ([#9268](https://github.com/googleapis/google-cloud-python/pull/9268))
+
+### Documentation
+- Fix intersphinx reference to requests. ([#9294](https://github.com/googleapis/google-cloud-python/pull/9294))
+- Link to correct TimeoutError in futures docs. ([#9216](https://github.com/googleapis/google-cloud-python/pull/9216))
+
+### Internal / Testing Changes
+- Adjust messaging RPC timeout settings (via synth). [#9279](https://github.com/googleapis/google-cloud-python/pull/9279)
+
+## 1.0.0
+
+08-29-2019 09:27 PDT
+
+### Implementation Changes
+- Add 'ReceivedMessage.delivery_attempt' field (via synth). ([#9098](https://github.com/googleapis/google-cloud-python/pull/9098))
+- Remove send/recv msg size limit, update docstrings (via synth). ([#8964](https://github.com/googleapis/google-cloud-python/pull/8964))
+
+### Documentation
+- Update docstrings for client kwargs and fix return types uris ([#9037](https://github.com/googleapis/google-cloud-python/pull/9037))
+- Remove CI for gh-pages, use googleapis.dev for api_core refs. ([#9085](https://github.com/googleapis/google-cloud-python/pull/9085))
+- Remove compatability badges from READMEs. ([#9035](https://github.com/googleapis/google-cloud-python/pull/9035))
+
+### Internal / Testing Changes
+- Add dead-letter-policy field in preparation for its implementation (via synth) ([#9078](https://github.com/googleapis/google-cloud-python/pull/9078))
+
+## 0.45.0
+
+07-31-2019 02:03 PDT
+
+
+### Implementation Changes
+
+- Remove deprecated methods and settings ([#8836](https://github.com/googleapis/google-cloud-python/pull/8836))
+
+
+### Documentation
+
+- Use double backticks for ReST correctness. ([#8829](https://github.com/googleapis/google-cloud-python/pull/8829))
+- Update intersphinx mapping for requests. ([#8805](https://github.com/googleapis/google-cloud-python/pull/8805))
+
+## 0.44.0
+
+07-29-2019 04:28 PDT
+
+
+### Implementation Changes
+
+- PubSub: Deprecate several FlowControl settings and things in Message class ([#8796](https://github.com/googleapis/google-cloud-python/pull/8796))
+
+### Documentation
+
+- Pub/Sub: document regional endpoint ([#8789](https://github.com/googleapis/google-cloud-python/pull/8789))
+
+## 0.43.0
+
+07-24-2019 17:13 PDT
+
+
+### Implementation Changes
+- Accomodate new location of 'IAMPolicyStub' (via synth). ([#8680](https://github.com/googleapis/google-cloud-python/pull/8680))
+- Use kwargs in test_subscriber_client ([#8414](https://github.com/googleapis/google-cloud-python/pull/8414))
+
+### New Features
+- Add `options_` argument to clients' `get_iam_policy`; pin black version (via synth). ([#8657](https://github.com/googleapis/google-cloud-python/pull/8657))
+- Add 'client_options' support, update list method docstrings (via synth). ([#8518](https://github.com/googleapis/google-cloud-python/pull/8518))
+
+### Dependencies
+- Bump minimum version for google-api-core to 1.14.0. ([#8709](https://github.com/googleapis/google-cloud-python/pull/8709))
+- Update pin for 'grpc-google-iam-v1' to 0.12.3+. ([#8647](https://github.com/googleapis/google-cloud-python/pull/8647))
+
+### Documentation
+- Link to googleapis.dev documentation in READMEs. ([#8705](https://github.com/googleapis/google-cloud-python/pull/8705))
+- Add compatibility check badges to READMEs. ([#8288](https://github.com/googleapis/google-cloud-python/pull/8288))
+- Fix typo in publisher index. ([#8619](https://github.com/googleapis/google-cloud-python/pull/8619))
+- Document how to choose the PubSub auth method ([#8429](https://github.com/googleapis/google-cloud-python/pull/8429))
+- Document different PuSub received message types ([#8468](https://github.com/googleapis/google-cloud-python/pull/8468))
+- PubSub: Document batch settings, make synth operations idempotent ([#8448](https://github.com/googleapis/google-cloud-python/pull/8448))
+- Add custom docstrings for FlowControl enum and values (via synth). ([#8426](https://github.com/googleapis/google-cloud-python/pull/8426))
+
+### Internal / Testing Changes
+- Add docs job to publish to googleapis.dev. ([#8464](https://github.com/googleapis/google-cloud-python/pull/8464))
+- Add system tests for PubSub clients ([#8277](https://github.com/googleapis/google-cloud-python/pull/8277))
+
+## 0.42.1
+
+06-18-2019 15:14 PDT
+
+
+### Implementation Changes
+- Increase the minimum allowed version for api core. ([#8419](https://github.com/googleapis/google-cloud-python/pull/8419))
+- Allow kwargs to be passed to create_channel. ([#8399](https://github.com/googleapis/google-cloud-python/pull/8399))
+
+## 0.42.0
+
+06-18-2019 11:32 PDT
+
+### Implementation Changes
+- Core: Mitigate busy reopen loop in ResumableBidiRpc consuming 100% CPU ([#8193](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8193))
+- Pub/Sub: Increase initial_rpc_timeout for messaging (via synth). ([#8219](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8219))
+- PubSub: Release the state lock before calling the publish api ([#8234](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8234))
+- Pub/Sub: Expose publish retry settings ([#8231](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8231))
+- Prevent unhandled background error on SPM shutdown ([#8111](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8111))
+- Update timeouts, blacken noxfile.py, setup.py (via synth). ([#8128](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8128))
+- PubSub: Fix streaming pull incorrectly handling FlowControl max_messages setting ([#7948](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7948))
+
+### Documentation
+- Document PubSub FlowControl settings ([#8293](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8293))
+- Replace readthedocs links with links to github docs. ([#8291](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8291))
+- Pub/Sub: surface publish future in documentation ([#8229](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8229))
+- Pubsub: Separate subscriber and publish future documentation. ([#8205](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8205))
+- Drop mention of long-removed 'policy' object. ([#8081](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8081))
+
+### Internal / Testing Changes
+- Pub/Sub: staticmethod check ([#8091](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8091))
+- Add empty lines (via synth). ([#8067](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8067))
+
+## 0.41.0
+
+05-15-2019 13:57 PDT
+
+
+### New Features
+- Add `kms_key_name` arg to `create_topic`; remove BETA warnings (via synth). ([#7936](https://github.com/googleapis/google-cloud-python/pull/7936))
+- Add message ordering (via synth). ([#7551](https://github.com/googleapis/google-cloud-python/pull/7551))
+
+### Implementation Changes
+- Propagate subscribe callback errors to main thread ([#7954](https://github.com/googleapis/google-cloud-python/pull/7954))
+- Fix pubsub Streaming Pull shutdown on RetryError ([#7863](https://github.com/googleapis/google-cloud-python/pull/7863))
+- Make PubSub subscriber Scheduler inherit from ABC ([#7690](https://github.com/googleapis/google-cloud-python/pull/7690))
+- Add routing header to method metadata (via synth). ([#7623](https://github.com/googleapis/google-cloud-python/pull/7623))
+
+### Internal / Testing Changes
+- Remove classifier for Python 3.4 for end-of-life. ([#7535](https://github.com/googleapis/google-cloud-python/pull/7535))
+- Add nox session `docs` (via synth). ([#7778](https://github.com/googleapis/google-cloud-python/pull/7778))
+- Pub/Sub (nit): wrong var name in sample ([#7705](https://github.com/googleapis/google-cloud-python/pull/7705))
+
+## 0.40.0
+
+03-15-2019 14:09 PDT
+
+
+### Implementation Changes
+- Propagate 'RetryError' in 'PublisherClient.publish'. ([#7071](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7071))
+- Protoc-generated serialization update.. ([#7091](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7091))
+
+### New Features
+- Add 'authentication_method' to 'PushConfig' (via synth). ([#7512](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7512))
+- Add protos as an artifact to library ([#7205](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7205))
+- Pub/sub: pass transport w/ custom channel to GAPIC API clients. ([#7008](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7008))
+
+### Dependencies
+
+### Documentation
+- Updated client library documentation URLs. ([#7307](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7307))
+- Update copyright headers
+- Fix broken docstring cross-reference links. ([#7132](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7132))
+- Docstring changes from updates to .proto files. ([#7054](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7054))
+- Pick up stub docstring fix in GAPIC generator. ([#6978](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6978))
+
+### Internal / Testing Changes
+- Copy proto files alongside protoc versions.
+
+## 0.39.1
+
+12-17-2018 16:57 PST
+
+
+### Implementation Changes
+- Initialize `StreamingPullFuture._cancelled` as True. ([#6901](https://github.com/googleapis/google-cloud-python/pull/6901))
+- Import `iam.policy` from `google.api_core`. ([#6741](https://github.com/googleapis/google-cloud-python/pull/6741))
+
+### Documentation
+- Document Python 2 deprecation ([#6910](https://github.com/googleapis/google-cloud-python/pull/6910))
+- Emphasize that returned futures may differ from stdlib futures. ([#6875](https://github.com/googleapis/google-cloud-python/pull/6875))
+
+### Internal / Testing Changes
+- Add baseline for synth.metadata
+- Update noxfile.
+- blacken all gen'd libs ([#6792](https://github.com/googleapis/google-cloud-python/pull/6792))
+- omit local deps ([#6701](https://github.com/googleapis/google-cloud-python/pull/6701))
+- Run black at end of synth.py ([#6698](https://github.com/googleapis/google-cloud-python/pull/6698))
+- Run Black on Generated libraries ([#6666](https://github.com/googleapis/google-cloud-python/pull/6666))
+- Add templates for flake8, coveragerc, noxfile, and black. ([#6642](https://github.com/googleapis/google-cloud-python/pull/6642))
+
+## 0.39.0
+
+11-27-2018 13:32 PST
+
+### Implementation Changes
+- Pick up fixes to GAPIC generator. ([#6503](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6503))
+- Override client classmethod factories inherited from GAPIC. ([#6453](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6453))
+- Fix imports for hand-written client docstring examples. ([#6345](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6345))
+- Fix path for patch of 'bidi' elements. ([#6243](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6243))
+- Move bidi to api-core. ([#6211](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6211))
+- Re-generate library using pubsub/synth.py ([#6059](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6059))
+- Re-generate library using pubsub/synth.py ([#5978](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5978))
+
+### New Features
+- Add 'expiration_policy' to subscriber client. ([#6223](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6223))
+
+### Dependencies
+- Bump minimum 'api_core' version for all GAPIC libs to 1.4.1. ([#6391](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6391))
+- Update IAM version in dependencies. ([#6362](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6362))
+- Bump minimum 'api_core' version to '1.4.1'. ([#6134](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6134))
+
+### Documentation
+- Fix client_info bug, update docstrings. ([#6418](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6418))
+- Fix docstring reference to wrong future class. ([#6382](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6382))
+- Normalize use of support level badges. ([#6159](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6159))
+- Update subscriber example in README to current patterns. ([#6194](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6194))
+- Prep pubsub docs for repo split. ([#6001](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6001))
+
+### Internal / Testing Changes
+- Fix error from new flake8 version. ([#6346](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6346))
+- Use new Nox. ([#6175](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6175))
+
+## 0.38.0
+
+### Implementation Changes
+
+- Fix race condition in recv()'s usage of self.call. ([#5935](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5935))
+- Re-generate the underlying library from protos. ([#5953](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5953))
+- Change 'BatchSettings.max_bytes' default. ([#5899](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5899))
+- Fix race condition where pending Ack IDs can be modified by another thread. ([#5929](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5929))
+
+### Internal / Testing Changes
+
+- Nox: use inplace installs ([#5865](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5865))
+
+## 0.37.2
+
+### Implementation Changes
+
+- Fix classmethod wrapping (#5826)
+
+### Documentation
+
+- Fix Sphinx rendering for publisher client. (#5822)
+
+### Internal / Testing Changes
+
+- Re-generate library, removing obsolete synth modifications. (#5825)
+- Add test for testing invoking a wrapped class method on the class itself (#5828)
+
+## 0.37.1
+
+### Implementation Changes
+
+- Make get_initial_request more resilient to race conditions. (#5803)
+
+## 0.37.0
+
+### Implementation Changes
+
+- Make Publisher batch-related interfaces private (#5784)
+
+## 0.36.0
+
+### Implementation Changes
+- Pubsub: Make 'Message.publish_time' return datetime (#5633)
+- Ensure SPM methods check that 'self._consumer' is not None before use. (#5758)
+
+### New Features
+- PubSub: add geo-fencing support (#5769)
+- Add 'Message.ack_id' property. (#5693)
+
+## 0.35.4
+
+### Implementation Changes
+
+- Recover streams during the gRPC error callback. (#5446)
+- Use operational lock when checking for activity on streams. (#5445)
+
+## 0.35.3
+
+### Implementation Changes
+
+- Add additional error handling to unary RPCs (#5438)
+
+## 0.35.2
+
+### Implementation Changes
+- Add heartbeating to the streaming pull manager (#5413)
+- Fix retrying of bidirectional RPCs and closing the streaming pull manager (#5412)
+
+## 0.35.1
+
+### Implementation Changes
+- Catch errors when re-retying send() or recv() in addition to open() (#5402)
+
+## 0.35.0
+
+### Implementation Changes
+
+- Send requests during streaming pull over a separate unary RPC (#5377)
+- Initialize references to helper threads before starting them (#5374)
+- Make leaser exit more quickly (#5373)
+- Make re-open failures bubble to callbacks (#5372)
+- Avoid overwriting '__module__' of messages from shared modules. (#5364)
+- Normalize overflow handling for max count and bytes (#5343)
+
+### New Features
+
+- Restore the synchronous pull method (#5379)
+- Promote subscribe_experimental() to subscribe(), remove old subscriber implementation. (#5274)
+- Wire up scheduler argument for subscribe() (#5279)
+
+### Documentation
+
+- Add link to streaming pull behavior documentation (#5378)
+- Fix example in subscribe's documentation (#5375)
+
+### Internal / Testing Changes
+
+- Add Test runs for Python 3.7 and remove 3.4 (#5295)
+- Modify system tests to use prerelease versions of grpcio (#5304)
+
+## 0.34.0
+
+### Implementation Changes
+
+- Lower the flow control defaults. (#5248)
+
+### New Features
+
+- A new implementation of the subscriber has been added. This is available as `SubscriberClient.subscribe_experimental`. In the next release, this will be replace the current `subscribe` method. If you use this, please report your findings to us on GitHub. (#5189, #5201, #5210, #5229, #5230, #5237, #5256)
+
+### Dependencies
+
+- Remove psutil dependency. (#5248)
+
+## 0.33.1
+
+### Implementation changes
+
+- Surface publish RPC errors back to the publish futures (#5124)
+- Make the pausable response iterator aware of the RPC state to prevent deadlock (#5108)
+- Properly handle graceful stop in request generator (#5097)
+
+## 0.33.0
+
+### Implementation changes
+
+- Drop leased messages after flow_control.max_lease_duration has passed. (#5020)
+- Fix mantain leases to not modack messages it just dropped (#5045)
+- Avoid race condition in maintain_leases by copying leased_messages (#5035)
+- Retry subscription stream on InternalServerError, Unknown, and GatewayTimeout (#5021)
+- Use the rpc's status to determine when to exit the request generator thread (#5054)
+- Fix missing iter on request stream (#5078)
+- Nack messages when the subscriber callback errors (#5019)
+
+### Testing
+
+- pubsub nox.py cleanup (#5056)
+- Fix test that checks for retryable exceptions (#5034)
+
+## 0.32.1
+
+### Dependencies
+
+- Update dependency range for api-core to include v1.0.0 releases (#4944)
+
+### Testing and internal changes
+
+- Install local dependencies when running lint (#4936)
+- Re-enable lint for tests, remove usage of pylint (#4921)
+
+## 0.32.0
+
+### Implementation changes
+
+- Added support for streaming pull receipts. (#4878)
+
+## 0.31.0
+
+### New features
+
+- Added the ability for subscriber to batch requests. (#4895)
+- Added pending request backpressure for subscriber. (#4892)
+
+### Implementation changes
+
+- Raise `ValueError` when a message is too large for a batch. (#4872)
+- Updated the default batch size to 10 MB. (#4857)
+- Allow a custom `Event` type in Pub / Sub futures. (#4643)
+
+### Documentation
+
+- Clarify that `modify_ack_deadline` resets the deadline. (#4822)
+
+### Testing
+
+- Fix unit test for default `max_bytes` value. (#4860)
+
+## 0.30.1
+
+### Notable Implementation Changes
+
+- Moving lock factory used in publisher client to the Batch
+ implementation (#4628).
+- Use a UUID (rather than a sentinel object) on `Future` (#4634).
+- Apply scopes to explicitly provided credentials if needed (#4594).
+ Fixes #4479. This feature comes as part of `google-api-core==0.1.3`.
+
+### Dependencies
+
+- Upgrading to `google-api-core==0.1.3` which depends on the latest
+ `grpcio==1.8.2` (#4642). This fixes #4600. For details, see related
+ gRPC [bug](https://github.com/grpc/grpc/issues/9688) and
+ [fix](https://github.com/grpc/grpc/pull/13665).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.30.1/
+
+## 0.30.0
+
+### Notable Implementation Changes
+
+- Dropping redundant `Policy._paused` data member (#4568).
+- Removing redundant "active" check in policy (#4603).
+- Adding a `Consumer.active` property (#4604).
+- Making it impossible to call `Policy.open()` on an already opened
+ policy (#4606).
+- **Bug fix** (#4575): Fix bug with async publish for batches. There
+ were two related bugs. The first: if a batch exceeds the `max_messages`
+ from the batch settings, then the `commit()` will fail. The second:
+ when a "monitor" worker calls `commit()` after `max_latency` seconds,
+ a failure can occur if a new message is added to the batch **during**
+ the commit. To fix, the following changes were implemented:
+
+ - Adding a "STARTING" status for `Batch.commit()` (#4614). This
+ fixes the issue when the batch exceeds `max_messages`.
+ - Adding extra check in `Batch.will_accept` for the number of
+ messages (#4612).
+ - Moving `will_accept()` check out of `PublisherClient.batch()`
+ factory (#4613).
+ - Checking `Batch.will_accept` in thread-safe way (#4616).
+- **Breaking API change**: As part of #4613, changing `PublisherClient.batch()`
+ to no longer accept a `message` (since the `will_accept` check needs to
+ happen in a more concurrency friendly way). In addition, changing the
+ `create` argument so that it means "create even if batch already exists"
+ rather than "create if missing".
+
+### Documentation
+
+- Add more explicit documentation for `Message.attributes` (#4601).
+- Make `Message.__repr__` a bit prettier / more useful (#4602).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.30.0/
+
+## 0.29.4
+
+### Notable Implementation Changes
+
+- **Bug fix**: Restore previous behavior of the subscription lease
+ maintenance worker. This was accidentally "stopped" in `0.29.3`
+ due to a change in implementation that went from an `active`
+ boolean to an "inactive" / `stopped` boolean, so `True` became
+ `False` and vice-versa (#4564).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.4/
+
+## 0.29.3
+
+### Notable Implementation Changes
+
+- In subscription consumer thread: Making sure the request generator
+ attached to an inactive bidirectional streaming pull is stopped before
+ spawning a new request generator. This way we have a (fairly strong)
+ guarantee that requests in the queue don't get sent into an inactive
+ stream (#4503, #4554).
+- Adding `pause` / `resume` to subscription consumer thread and using these
+ methods during flow control. The previous implementation tried to close the
+ subscription (which involved 3 worker threads and 10 executors in a thread
+ pool) and then re-open a new subscription. But, this was not entirely
+ possible to shut down correctly from **within** one of the worker threads.
+ Instead, we only pause the worker (of the 3) that is pulling new responses
+ from the bidirectional streaming pull (#4558).
+- **Bug fix** (#4516): Using `max` where `min` was used by mistake to
+ ensure the number of bytes tracked for subscription flow control
+ remained non-negative (#4514).
+- Raising `TypeError` if `SubscriberClient.subscribe` receives a
+ non-callable callback (#4497).
+- Shutting down thread pool executor when closing a subscriber
+ policy (#4522).
+- Renaming `Policy.on_callback_request` to `Policy.dispatch_callback`
+ and making the behavior much less dynamic (#4511).
+- Make sure subscription consumer thread doesn't try to join itself
+ when exiting in error (#4540).
+
+### Dependencies
+
+- Upgrading `google-api-core` dependency to latest revision (`0.1.2`)
+ since we rely on the latest version of the `concurrent.futures` backport
+ to provide the `thread_name_prefix` argument for thread pool
+ executor (#4521, #4559).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.3/
+
+## 0.29.2
+
+### Notable Implementation Changes
+
+- **Bug fix** (#4463): Making a subscription consumer actually stop
+ running after encountering an exception (#4472, #4498). This bug
+ is the **only** reason for the `0.29.2` release.
+- Thread Changes
+
+ - Added names to all threads created directly by Pub / Sub (#4474,
+ #4476, #4480). Also removing spaces and colons from thread
+ names (#4476).
+- Logging changes
+
+ - Adding debug logs when lease management exits (#4484)
+ - Adding debug logs when `QueueCallbackThread` exits (#4494).
+ Instances handle the processing of messages in a
+ subscription (e.g. to `ack`).
+ - Using a named logger in `publisher.batch.thread` (#4473)
+ - Adding newlines before logging protobuf payloads (#4471)
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.2/
+
+## 0.29.1
+
+### Notable Implementation Changes
+
+- **Bug fix** (#4234): Adding retries for connection `UNAVAILABLE`. This
+ bug made the Pub / Sub client mostly unusable for subscribers to topics
+ that don't have a steady stream of messages. After ~2 minutes of inactivity,
+ the gRPC connection would timeout and raise `UNAVAILABLE` locally, i.e. not
+ due to a response from the backend. (#4444)
+- Updating autogenerated packages (#4438)
+
+### Documentation
+
+- Fixing broken examples in quick start (#4398)
+- Fixing broken example in README (#4402, h/t to @mehmetboraezer)
+- Updating old/dead link to usage doc in README (#4406, h/t to @mehmetboraezer)
+
+### Dependencies
+
+- Dropping dependency on `google-cloud-core` in exchange for
+ `google-api-core` (#4438)
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.1/
+
+## 0.29.0
+
+### Notable Implementation Changes
+
+- Honor `max_messages` always (#4262)
+- Add futures for subscriptions (#4265)
+- Set gRPC message options and keepalive (#4269)
+
+### Documentation
+
+- Added link to "Python Development Environment Setup Guide" in
+ project README (#4187, h/t to @michaelawyu)
+
+### Dependencies
+
+- Upgrading to `google-cloud-core >= 0.28.0` and adding dependency
+ on `google-api-core` (#4221, #4280)
+- Deferring to `google-api-core` for `grpcio` and
+ `googleapis-common-protos` dependencies (#4096, #4098)
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.0/
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/README.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/README.rst
new file mode 100644
index 000000000000..ed1965b8834d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/README.rst
@@ -0,0 +1,233 @@
+Python Client for Google Cloud Pub / Sub
+========================================
+
+|GA| |pypi| |versions|
+
+`Google Cloud Pub / Sub`_ is a fully-managed real-time messaging service that
+allows you to send and receive messages between independent applications. You
+can leverage Cloud Pub/Sub’s flexibility to decouple systems and components
+hosted on Google Cloud Platform or elsewhere on the Internet. By building on
+the same technology Google uses, Cloud Pub / Sub is designed to provide “at
+least once” delivery at low latency with on-demand scalability to 1 million
+messages per second (and beyond).
+
+Publisher applications can send messages to a ``topic`` and other applications
+can subscribe to that topic to receive the messages. By decoupling senders and
+receivers, Google Cloud Pub/Sub allows developers to communicate between
+independently written applications.
+
+- `Product Documentation`_
+- `Client Library Documentation`_
+
+.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg
+ :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability
+.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-pubsub.svg
+ :target: https://pypi.org/project/google-cloud-pubsub/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-pubsub.svg
+ :target: https://pypi.org/project/google-cloud-pubsub/
+.. _Google Cloud Pub / Sub: https://cloud.google.com/pubsub/
+.. _Product Documentation: https://cloud.google.com/pubsub/docs
+.. _Client Library Documentation: https://cloud.google.com/python/docs/reference/pubsub/latest
+
+Quick Start
+-----------
+
+In order to use this library, you first need to go through the following steps:
+
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Google Cloud Pub / Sub API.`_
+4. `Setup Authentication.`_
+
+.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
+.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
+.. _Enable the Google Cloud Pub / Sub API.: https://cloud.google.com/pubsub
+.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
+
+Installation
+~~~~~~~~~~~~
+
+Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
+create isolated Python environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
+
+With `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
+
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
+
+
+Supported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Python >= 3.7
+
+Deprecated Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Python <= 3.6.
+
+The last version of this library compatible with Python 2.7 is google-cloud-pubsub==1.7.0.
+
+
+Mac/Linux
+^^^^^^^^^
+
+.. code-block:: console
+
+ pip install virtualenv
+ virtualenv
+ source /bin/activate
+ /bin/pip install google-cloud-pubsub
+
+
+Windows
+^^^^^^^
+
+.. code-block:: console
+
+ pip install virtualenv
+ virtualenv
+ \Scripts\activate
+ \Scripts\pip.exe install google-cloud-pubsub
+
+
+Example Usage
+~~~~~~~~~~~~~
+
+Publishing
+^^^^^^^^^^
+
+To publish data to Cloud Pub/Sub you must create a topic, and then publish
+messages to it
+
+.. code-block:: python
+
+ import os
+ from google.cloud import pubsub_v1
+
+ publisher = pubsub_v1.PublisherClient()
+ topic_name = 'projects/{project_id}/topics/{topic}'.format(
+ project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
+ topic='MY_TOPIC_NAME', # Set this to something appropriate.
+ )
+ publisher.create_topic(name=topic_name)
+ future = publisher.publish(topic_name, b'My first message!', spam='eggs')
+ future.result()
+
+To learn more, consult the `publishing documentation`_.
+
+.. _publishing documentation: https://cloud.google.com/python/docs/reference/pubsub/latest
+
+
+Subscribing
+^^^^^^^^^^^
+
+To subscribe to data in Cloud Pub/Sub, you create a subscription based on
+the topic, and subscribe to that, passing a callback function.
+
+.. code-block:: python
+
+ import os
+ from google.cloud import pubsub_v1
+
+ topic_name = 'projects/{project_id}/topics/{topic}'.format(
+ project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
+ topic='MY_TOPIC_NAME', # Set this to something appropriate.
+ )
+
+ subscription_name = 'projects/{project_id}/subscriptions/{sub}'.format(
+ project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
+ sub='MY_SUBSCRIPTION_NAME', # Set this to something appropriate.
+ )
+
+ def callback(message):
+ print(message.data)
+ message.ack()
+
+ with pubsub_v1.SubscriberClient() as subscriber:
+ subscriber.create_subscription(
+ name=subscription_name, topic=topic_name)
+ future = subscriber.subscribe(subscription_name, callback)
+
+The future returned by the call to ``subscriber.subscribe`` can be used to
+block the current thread until a given condition obtains:
+
+.. code-block:: python
+
+ try:
+ future.result()
+ except KeyboardInterrupt:
+ future.cancel()
+
+It is also possible to pull messages in a synchronous (blocking) fashion. To
+learn more about subscribing, consult the `subscriber documentation`_.
+
+.. _subscriber documentation: https://cloud.google.com/python/docs/reference/pubsub/latest
+
+
+Authentication
+^^^^^^^^^^^^^^
+
+It is possible to specify the authentication method to use with the Pub/Sub
+clients. This can be done by providing an explicit `Credentials`_ instance. Support
+for various authentication methods is available from the `google-auth`_ library.
+
+For example, to use JSON Web Tokens, provide a `google.auth.jwt.Credentials`_ instance:
+
+.. code-block:: python
+
+ import json
+ from google.auth import jwt
+
+ service_account_info = json.load(open("service-account-info.json"))
+ audience = "https://pubsub.googleapis.com/google.pubsub.v1.Subscriber"
+
+ credentials = jwt.Credentials.from_service_account_info(
+ service_account_info, audience=audience
+ )
+
+ subscriber = pubsub_v1.SubscriberClient(credentials=credentials)
+
+ # The same for the publisher, except that the "audience" claim needs to be adjusted
+ publisher_audience = "https://pubsub.googleapis.com/google.pubsub.v1.Publisher"
+ credentials_pub = credentials.with_claims(audience=publisher_audience)
+ publisher = pubsub_v1.PublisherClient(credentials=credentials_pub)
+
+.. _Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.credentials.html#google.auth.credentials.Credentials
+.. _google-auth: https://google-auth.readthedocs.io/en/latest/index.html
+.. _google.auth.jwt.Credentials: https://google-auth.readthedocs.io/en/latest/reference/google.auth.jwt.html#google.auth.jwt.Credentials
+
+
+Versioning
+----------
+
+This library follows `Semantic Versioning`_.
+
+It is currently in major version one (1.y.z), which means that the public API should be considered stable.
+
+.. _Semantic Versioning: http://semver.org/
+
+Contributing
+------------
+
+Contributions to this library are always welcome and highly encouraged.
+
+See the `CONTRIBUTING doc`_ for more information on how to get started.
+
+.. _CONTRIBUTING doc: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst
+
+Community
+---------
+
+Google Cloud Platform Python developers hang out in `Slack`_ in the ``#python``
+channel, click here to `get an invitation`_.
+
+.. _Slack: https://googlecloud-community.slack.com
+.. _get an invitation: https://gcp-slack.appspot.com/
+
+License
+-------
+
+Apache 2.0 - See `the LICENSE`_ for more information.
+
+.. _the LICENSE: https://github.com/googleapis/google-cloud-python/blob/main/LICENSE
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/UPGRADING.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/UPGRADING.md
new file mode 100644
index 000000000000..83081c1ac69e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/UPGRADING.md
@@ -0,0 +1,201 @@
+# 2.0.0 Migration Guide
+
+The 2.0 release of the `google-cloud-pubsub` client is a significant upgrade based
+on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python),
+and includes substantial interface changes. Existing code written for earlier versions
+of this library will likely require updates to use this version. This document
+describes the changes that have been made, and what you need to do to update your usage.
+
+If you experience issues or have questions, please file an
+[issue](https://github.com/googleapis/python-pubsub/issues).
+
+
+## Supported Python Versions
+
+> **WARNING**: Breaking change
+
+The 2.0.0 release requires Python 3.6+.
+
+
+## Method Calls
+
+> **WARNING**: Breaking change
+
+Almost all methods that send requests to the backend expect request objects. We
+provide a script that will convert most common use cases.
+
+* Install the library with the `libcst` extra.
+
+```py
+python3 -m pip install google-cloud-pubsub[libcst]
+```
+
+* The script `fixup_pubsub_v1_keywords.py` is shipped with the library. It expects
+an input directory (with the code to convert) and an empty destination directory.
+
+```sh
+$ scripts/fixup_pubsub_v1_keywords.py --input-directory .samples/ --output-directory samples/
+```
+
+**Before:**
+```py
+from google.cloud import pubsub
+
+publisher = pubsub.PublisherClient()
+
+project_path = "projects/{}".format(PROJECT_ID)
+topics = publisher.list_topics(project_path)
+```
+
+
+**After:**
+```py
+from google.cloud import pubsub
+
+publisher = pubsub.PublisherClient()
+
+project_path = f"projects/{PROJECT_ID}"
+topics = publisher.list_topics(request={"project": project_path})
+```
+
+### More Details
+
+In `google-cloud-pubsub<2.0.0`, parameters required by the API were positional
+parameters and optional parameters were keyword parameters.
+
+**Before:**
+```py
+ def list_topics(
+ self,
+ project,
+ page_size=None,
+ retry=google.api_core.gapic_v1.method.DEFAULT,
+ timeout=google.api_core.gapic_v1.method.DEFAULT,
+ metadata=None,
+ ):
+```
+
+In the 2.0.0 release, almost all methods that interact with the backend have a single
+positional parameter `request`. Method docstrings indicate whether a parameter is
+required or optional.
+
+> **NOTE:** The exception are hand written methods such as `publisher.publish()` and
+> `subscriber.subscribe()` that implement additional logic (e.g. request batching) and
+> sit on top of the API methods from the generated parts of the library. The signatures
+> of these methods have in large part been preserved.
+
+Some methods have additional keyword only parameters. The available parameters depend
+on the [`google.api.method_signature` annotation](https://github.com/googleapis/python-pubsub/blob/main/google/cloud/pubsub_v1/proto/pubsub.proto#L88)
+specified by the API producer.
+
+
+**After:**
+```py
+ def list_topics(
+ self,
+ request: pubsub.ListTopicsRequest = None,
+ *,
+ project: str = None,
+ retry: retries.Retry = gapic_v1.method.DEFAULT,
+ timeout: google.pubsub_v1.types.TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicsPager:
+```
+
+> **NOTE:** The `request` parameter and flattened keyword parameters for the API are
+> mutually exclusive. Passing both will result in an error.
+
+
+Both of these calls are valid:
+
+```py
+response = client.list_topics(
+ request={
+ "project": project_path,
+ "metadata": [("foo", "bar"), ("baz", "quux")],
+ }
+)
+```
+
+```py
+response = client.list_topics(
+ project=project_path,
+ metadata=[("foo", "bar"), ("baz", "quux")],
+)
+```
+
+This call is invalid because it mixes `request` with a keyword argument `metadata`.
+Executing this code will result in an error:
+
+```py
+response = client.synthesize_speech(
+ request={"project": project_path},
+ metadata=[("foo", "bar"), ("baz", "quux")],
+)
+```
+
+> **NOTE:** The `request` parameter of some methods can also contain a more rich set of
+> options that are otherwise not available as explicit keyword only parameters, thus
+> these _must_ be passed through `request`.
+
+
+## Removed Utility Methods
+
+> **WARNING**: Breaking change
+
+Some utility methods such as publisher client's `subscription_path()` have been removed
+and now only exist in the relevant client, e.g. `subscriber.subscription_path()`.
+
+The `project_path()` method has been removed from both the publisher and subscriber
+client, this path must now be constructed manually:
+```py
+project_path = f"projects/{PROJECT_ID}"
+```
+
+## Removed `client_config` Parameter
+
+The publisher and subscriber clients cannot be constructed with `client_config`
+argument anymore. If you want to customize retry and timeout settings for a particular
+method, you need to do it upon method invocation by passing the custom `timeout` and
+`retry` arguments, respectively.
+
+
+## Custom Retry and Timeout settings for Publisher Client
+
+The ``publisher_options`` parameter to the Publisher Client, as well as all of the
+client's methods, now accept custom retry and timeout settings:
+
+```py
+custom_retry = api_core.retry.Retry(
+ initial=0.250, # seconds (default: 0.1)
+ maximum=90.0, # seconds (default: 60.0)
+ multiplier=1.45, # default: 1.3
+ deadline=300.0, # seconds (default: 60.0)
+ predicate=api_core.retry.if_exception_type(
+ api_core.exceptions.Aborted,
+ api_core.exceptions.DeadlineExceeded,
+ api_core.exceptions.InternalServerError,
+ api_core.exceptions.ResourceExhausted,
+ api_core.exceptions.ServiceUnavailable,
+ api_core.exceptions.Unknown,
+ api_core.exceptions.Cancelled,
+ ),
+)
+
+custom_timeout=api_core.timeout.ExponentialTimeout(
+ initial=1.0,
+ maximum=10.0,
+ multiplier=1.0,
+ deadline=300.0,
+)
+
+publisher = pubsub_v1.PublisherClient(
+ publisher_options = pubsub_v1.types.PublisherOptions(
+ retry=custom_retry,
+ timeout=custom_timeout,
+ ),
+)
+```
+
+The timeout can be either an instance of `google.api_core.timeout.ConstantTimeout`,
+or an instance of `google.api_core.timeout.ExponentialTimeout`, as in the example.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/README.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/README.rst
new file mode 120000
index 000000000000..89a0106941ff
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/README.rst
@@ -0,0 +1 @@
+../README.rst
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/UPGRADING.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/UPGRADING.md
new file mode 120000
index 000000000000..01097c8c0fb8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/UPGRADING.md
@@ -0,0 +1 @@
+../UPGRADING.md
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/_static/custom.css b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/_static/custom.css
new file mode 100644
index 000000000000..b0a295464b23
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/_static/custom.css
@@ -0,0 +1,20 @@
+div#python2-eol {
+ border-color: red;
+ border-width: medium;
+}
+
+/* Ensure minimum width for 'Parameters' / 'Returns' column */
+dl.field-list > dt {
+ min-width: 100px
+}
+
+/* Insert space between methods for readability */
+dl.method {
+ padding-top: 10px;
+ padding-bottom: 10px
+}
+
+/* Insert empty space between classes */
+dl.class {
+ padding-bottom: 50px
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/_templates/layout.html b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/_templates/layout.html
new file mode 100644
index 000000000000..6316a537f72b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/_templates/layout.html
@@ -0,0 +1,50 @@
+
+{% extends "!layout.html" %}
+{%- block content %}
+{%- if theme_fixed_sidebar|lower == 'true' %}
+
+ {{ sidebar() }}
+ {%- block document %}
+
+ {%- if render_sidebar %}
+
+ {%- endif %}
+
+ {%- block relbar_top %}
+ {%- if theme_show_relbar_top|tobool %}
+
+
+ {{- rellink_markup () }}
+
+ {%- endif %}
+ {% endblock %}
+
+
+
+ As of January 1, 2020 this library no longer supports Python 2 on the latest released version.
+ Library versions released prior to that date will continue to be available. For more information please
+ visit
Python 2 support on Google Cloud .
+
+ {% block body %} {% endblock %}
+
+
+ {%- block relbar_bottom %}
+ {%- if theme_show_relbar_bottom|tobool %}
+
+
+ {{- rellink_markup () }}
+
+ {%- endif %}
+ {% endblock %}
+
+ {%- if render_sidebar %}
+
+ {%- endif %}
+
+ {%- endblock %}
+
+
v documentation".
+# html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a
+ Subscriber Client
+ Types
+
+
+Migration Guide
+---------------
+
+See the guide below for instructions on migrating to the 2.x release of this library.
+
+.. toctree::
+ :maxdepth: 2
+
+ UPGRADING
+
+
+Changelog
+---------
+
+For a list of all ``google-cloud-pubsub`` releases:
+
+.. toctree::
+ :maxdepth: 2
+
+ changelog
+
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/multiprocessing.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/multiprocessing.rst
new file mode 100644
index 000000000000..536d17b2ea65
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/multiprocessing.rst
@@ -0,0 +1,7 @@
+.. note::
+
+ Because this client uses :mod:`grpc` library, it is safe to
+ share instances across threads. In multiprocessing scenarios, the best
+ practice is to create client instances *after* the invocation of
+ :func:`os.fork` by :class:`multiprocessing.pool.Pool` or
+ :class:`multiprocessing.Process`.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/client.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/client.rst
new file mode 100644
index 000000000000..d1a54ff5e380
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/client.rst
@@ -0,0 +1,6 @@
+Publisher Client API (v1)
+=========================
+
+.. automodule:: google.cloud.pubsub_v1.publisher.client
+ :members:
+ :inherited-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/futures.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/futures.rst
new file mode 100644
index 000000000000..b02b9bf9039d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/futures.rst
@@ -0,0 +1,6 @@
+Futures
+=======
+
+.. automodule:: google.cloud.pubsub_v1.publisher.futures
+ :members:
+ :inherited-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/pagers.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/pagers.rst
new file mode 100644
index 000000000000..3bbfff33ca87
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/api/pagers.rst
@@ -0,0 +1,6 @@
+Pagers
+======
+
+.. automodule:: google.pubsub_v1.services.publisher.pagers
+ :members:
+ :inherited-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/index.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/index.rst
new file mode 100644
index 000000000000..2a0ad320eb3d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/publisher/index.rst
@@ -0,0 +1,187 @@
+Publishing Messages
+===================
+
+Publishing messages is handled through the
+:class:`~.pubsub_v1.publisher.client.Client` class (aliased as
+``google.cloud.pubsub.PublisherClient``). This class provides methods to
+create topics, and (most importantly) a
+:meth:`~.pubsub_v1.publisher.client.Client.publish` method that publishes
+messages to Pub/Sub.
+
+Instantiating a publishing client is straightforward:
+
+.. code-block:: python
+
+ from google.cloud import pubsub
+ publish_client = pubsub.PublisherClient()
+
+
+Publish a Message
+-----------------
+
+To publish a message, use the
+:meth:`~.pubsub_v1.publisher.client.Client.publish` method. This method accepts
+two positional arguments: the topic to publish to, and the body of the message.
+It also accepts arbitrary keyword arguments, which are passed along as
+attributes of the message.
+
+The topic is passed along as a string; all topics have the canonical form of
+``projects/{project_name}/topics/{topic_name}``.
+
+Therefore, a very basic publishing call looks like:
+
+.. code-block:: python
+
+ topic = 'projects/{project}/topics/{topic}'
+ future = publish_client.publish(topic, b'This is my message.')
+
+.. note::
+
+ The message data in Pub/Sub is an opaque blob of bytes, and as such, you
+ *must* send a ``bytes`` object in Python 3 (``str`` object in Python 2).
+ If you send a text string (``str`` in Python 3, ``unicode`` in Python 2),
+ the method will raise :exc:`TypeError`.
+
+ The reason it works this way is because there is no reasonable guarantee
+ that the same language or environment is being used by the subscriber,
+ and so it is the responsibility of the publisher to properly encode
+ the payload.
+
+If you want to include attributes, simply add keyword arguments:
+
+.. code-block:: python
+
+ topic = 'projects/{project}/topics/{topic}'
+ future = publish_client.publish(topic, b'This is my message.', foo='bar')
+
+
+Batching
+--------
+
+Whenever you publish a message, the publisher will automatically batch the
+messages over a small time window to avoid making too many separate requests to
+the service. This helps increase throughput.
+
+.. note::
+
+ By default, this uses ``threading``, and you will need to be in an
+ environment with threading enabled. It is possible to provide an
+ alternative batch class that uses another concurrency strategy.
+
+The way that this works is that on the first message that you send, a new batch
+is created automatically. For every subsequent message, if there is already a
+valid batch that is still accepting messages, then that batch is used. When the
+batch is created, it begins a countdown that publishes the batch once
+sufficient time has elapsed (by default, this is 0.01 seconds).
+
+If you need different batching settings, simply provide a
+:class:`~.pubsub_v1.types.BatchSettings` object when you instantiate the
+:class:`~.pubsub_v1.publisher.client.Client`:
+
+.. code-block:: python
+
+ from google.cloud import pubsub
+ from google.cloud.pubsub import types
+
+ client = pubsub.PublisherClient(
+ batch_settings=types.BatchSettings(
+ max_messages=500, # default 100
+ max_bytes=1024, # default 1 MB
+ max_latency=1 # default .01 seconds
+ ),
+ )
+
+The `max_bytes` argument is the maximum total size of the messages to collect
+before automatically publishing the batch, (in bytes) including any byte size
+overhead of the publish request itself. The maximum value is bound by the
+server-side limit of 10_000_000 bytes. The default value is 1 MB.
+
+The `max_messages` argument is the maximum number of messages to collect
+before automatically publishing the batch, the default value is 100 messages.
+
+The `max_latency` is the maximum number of seconds to wait for additional
+messages before automatically publishing the batch, the default is .01 seconds.
+
+
+Futures
+-------
+
+Every call to :meth:`~.pubsub_v1.publisher.client.Client.publish` returns
+an instance of :class:`~.pubsub_v1.publisher.futures.Future`.
+
+.. note::
+
+ The returned future conforms for the most part to the interface of
+ the standard library's :class:`~concurrent.futures.Future`, but might not
+ be usable in all cases which expect that exact implementaton.
+
+You can use this to ensure that the publish succeeded:
+
+.. code-block:: python
+
+ # The .result() method will block until the future is complete.
+ # If there is an error, it will raise an exception.
+ future = client.publish(topic, b'My awesome message.')
+ message_id = future.result()
+
+You can also attach a callback to the future:
+
+.. code-block:: python
+
+ # Callbacks receive the future as their only argument, as defined in
+ # the Future interface.
+ def callback(future):
+ message_id = future.result()
+ do_something_with(message_id)
+
+ # The callback is added once you get the future. If you add a callback
+ # and the future is already done, it will simply be executed immediately.
+ future = client.publish(topic, b'My awesome message.')
+ future.add_done_callback(callback)
+
+
+Publish Flow Control
+--------------------
+
+If publishing large amounts of messages or very large messages in quick
+succession, some of the publish requests might time out, especially if the
+bandwidth available is limited. To mitigate this the client can be
+configured with custom :class:`~.pubsub_v1.types.PublishFlowControl` settings.
+
+You can configure the maximum desired number of messages and their maximum total
+size, as well as the action that should be taken when the threshold is reached.
+
+.. code-block:: python
+
+ from google.cloud import pubsub_v1
+
+ client = pubsub_v1.PublisherClient(
+ publisher_options=pubsub_v1.types.PublisherOptions(
+ flow_control=pubsub_v1.types.PublishFlowControl(
+ message_limit=500,
+ byte_limit=2 * 1024 * 1024,
+ limit_exceeded_behavior=pubsub_v1.types.LimitExceededBehavior.BLOCK,
+ ),
+ ),
+ )
+
+The action to be taken on overflow can be one of the following:
+
+* :attr:`~.pubsub_v1.types.LimitExceededBehavior.IGNORE` (default): Ignore the
+ overflow and continue publishing the messages as normal.
+* :attr:`~.pubsub_v1.types.LimitExceededBehavior.ERROR`: Raise
+ :exc:`~.pubsub_v1.publisher.exceptions.FlowControlLimitError` and reject the message.
+* :attr:`~.pubsub_v1.types.LimitExceededBehavior.BLOCK`: Temporarily block in the
+ :meth:`~.pubsub_v1.publisher.client.Client.publish` method until there is
+ enough capacity available.
+
+
+API Reference
+-------------
+
+.. toctree::
+ :maxdepth: 2
+
+ api/client
+ api/futures
+ api/pagers
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/client.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/client.rst
new file mode 100644
index 000000000000..d26243eba820
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/client.rst
@@ -0,0 +1,6 @@
+Subscriber Client API (v1)
+==========================
+
+.. automodule:: google.cloud.pubsub_v1.subscriber.client
+ :members:
+ :inherited-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/futures.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/futures.rst
new file mode 100644
index 000000000000..fb0264279cf6
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/futures.rst
@@ -0,0 +1,6 @@
+Futures
+=======
+
+.. automodule:: google.cloud.pubsub_v1.subscriber.futures
+ :members:
+ :inherited-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/message.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/message.rst
new file mode 100644
index 000000000000..cc5b0e37c9b4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/message.rst
@@ -0,0 +1,5 @@
+Messages
+========
+
+.. autoclass:: google.cloud.pubsub_v1.subscriber.message.Message
+ :members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/pagers.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/pagers.rst
new file mode 100644
index 000000000000..367c65ca71d4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/pagers.rst
@@ -0,0 +1,6 @@
+Pagers
+======
+
+.. automodule:: google.pubsub_v1.services.subscriber.pagers
+ :members:
+ :inherited-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/scheduler.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/scheduler.rst
new file mode 100644
index 000000000000..06e839f219e6
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/api/scheduler.rst
@@ -0,0 +1,6 @@
+Scheduler
+=========
+
+.. automodule:: google.cloud.pubsub_v1.subscriber.scheduler
+ :members:
+ :inherited-members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/index.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/index.rst
new file mode 100644
index 000000000000..aa21cd37bce7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/subscriber/index.rst
@@ -0,0 +1,236 @@
+Subscribing to Messages
+=======================
+
+Subscribing to messages is handled through the
+:class:`~.pubsub_v1.subscriber.client.Client` class (aliased as
+``google.cloud.pubsub.SubscriberClient``). This class provides a
+:meth:`~.pubsub_v1.subscriber.client.Client.subscribe` method to
+attach to subscriptions on existing topics.
+
+Instantiating a subscriber client is straightforward:
+
+.. code-block:: python
+
+ from google.cloud import pubsub
+
+ with pubsub.SubscriberClient() as subscriber:
+ # ...
+
+Creating a Subscription
+-----------------------
+
+In Pub/Sub, a **subscription** is a discrete pull of messages from a topic.
+If multiple clients pull the same subscription, then messages are split
+between them. If multiple clients create a subscription each, then each client
+will get every message.
+
+.. note::
+
+ Remember that Pub/Sub operates under the principle of "everything at least
+ once". Even in the case where multiple clients pull the same subscription,
+ *some* redundancy is likely.
+
+Creating a subscription requires that you already know what topic you want
+to subscribe to, and it must already exist. Once you have that, it is easy:
+
+.. code-block:: python
+
+ # Substitute PROJECT, SUBSCRIPTION, and TOPIC with appropriate values for
+ # your application.
+
+ # from google.cloud import pubsub
+ # publisher = pubsub.PublisherClient()
+
+ topic_path = publisher.topic_path(PROJECT, TOPIC)
+
+ with pubsub.SubscriberClient() as subscriber:
+ sub_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
+ subscriber.create_subscription(request={"name": sub_path, "topic": topic_path})
+
+Once you have created a subscription (or if you already had one), the next
+step is to pull data from it.
+
+
+Pulling a Subscription Synchronously
+------------------------------------
+
+To pull the messages synchronously, use the client's
+:meth:`~.pubsub_v1.subscriber.client.Client.pull` method.
+
+.. code-block:: python
+
+ # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+
+ # Substitute PROJECT and SUBSCRIPTION with appropriate values for your
+ # application.
+ subscription_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
+ response = subscriber.pull(
+ request={
+ "subscription": subscription_path,
+ "max_messages": 5,
+ }
+ )
+
+ for msg in response.received_messages:
+ print("Received message:", msg.message.data)
+
+ ack_ids = [msg.ack_id for msg in response.received_messages]
+ subscriber.acknowledge(
+ request={
+ "subscription": subscription_path,
+ "ack_ids": ack_ids,
+ }
+ )
+
+The method returns a :class:`~.pubsub_v1.types.PullResponse` instance that
+contains a list of received :class:`~.pubsub_v1.types.ReceivedMessage`
+instances.
+
+If you want to **nack** some of the received messages (see :ref:`explaining-ack` below),
+you can use the :meth:`~.pubsub_v1.subscriber.client.Client.modify_ack_deadline`
+method and set their acknowledge deadlines to zero. This will cause them to
+be dropped by this client and the backend will try to re-deliver them.
+
+.. code-block:: python
+
+ # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+
+ ack_ids = [] # TODO: populate with `ack_ids` of the messages to NACK
+ ack_deadline_seconds = 0
+ subscriber.modify_ack_deadline(
+ request={
+ "subscription": subscription_path,
+ "ack_ids": ack_ids,
+ "ack_deadline_seconds": ack_deadline_seconds,
+ }
+ )
+
+
+Pulling a Subscription Asynchronously
+-------------------------------------
+
+The subscriber client uses the
+:meth:`~.pubsub_v1.subscriber.client.Client.subscribe` method to start a
+background thread to receive messages from Pub/Sub and calls a callback with
+each message received.
+
+.. code-block:: python
+
+ # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+
+ # Substitute PROJECT and SUBSCRIPTION with appropriate values for your
+ # application.
+ subscription_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
+ future = subscriber.subscribe(subscription_path, callback)
+
+This will return a
+:class:`~.pubsub_v1.subscriber.futures.StreamingPullFuture`. This future allows
+you to control the background thread that is managing the subscription.
+
+
+Subscription Callbacks
+----------------------
+
+Messages received from a subscription are processed asynchronously through
+**callbacks**.
+
+The basic idea: Define a function that takes one argument; this argument
+will be a :class:`~.pubsub_v1.subscriber.message.Message` instance, which is
+a convenience wrapper around the :class:`~.pubsub_v1.types.PubsubMessage`
+instance received from the server (and stored under the ``message`` attribute).
+
+This function should do whatever processing is necessary. At the end, the
+function should either :meth:`~.pubsub_v1.subscriber.message.Message.ack`
+or :meth:`~.pubsub_v1.subscriber.message.Message.nack` the message.
+
+When you call :meth:`~.pubsub_v1.subscriber.client.Client.subscribe`, you
+must pass the callback that will be used.
+
+Here is an example:
+
+.. code-block:: python
+
+ # Define the callback.
+ # Note that the callback is defined *before* the subscription is opened.
+ def callback(message):
+ do_something_with(message) # Replace this with your actual logic.
+ message.ack() # Asynchronously acknowledge the message.
+
+ # Wrap the following code in `with pubsub.SubscriberClient() as subscriber:`
+
+ # Substitute PROJECT and SUBSCRIPTION with appropriate values for your
+ # application.
+ subscription_path = subscriber.subscription_path(PROJECT, SUBSCRIPTION)
+
+ # Open the subscription, passing the callback.
+ future = subscriber.subscribe(subscription_path, callback)
+
+The :meth:`~.pubsub_v1.subscriber.client.Client.subscribe` method returns
+a :class:`~.pubsub_v1.subscriber.futures.StreamingPullFuture`, which is both
+the interface to wait on messages (e.g. block the primary thread) and to
+address exceptions.
+
+To block the thread you are in while messages are coming in the stream,
+use the :meth:`~.pubsub_v1.subscriber.futures.Future.result` method:
+
+.. code-block:: python
+
+ future.result()
+
+.. note: This will block forever assuming no errors or that ``cancel`` is never
+ called.
+
+You can also use this for error handling; any exceptions that crop up on a
+thread will be set on the future.
+
+.. code-block:: python
+
+ try:
+ future.result()
+ except Exception as ex:
+ # Close the subscriber if not using a context manager.
+ subscriber.close()
+ raise
+
+Finally, you can use
+:meth:`~.pubsub_v1.subscriber.futures.StreamingPullFuture.cancel` to stop
+receiving messages.
+
+
+.. code-block:: python
+
+ future.cancel()
+
+
+.. _explaining-ack:
+
+Explaining Ack
+--------------
+
+In Pub/Sub, the term **ack** stands for "acknowledge". You should ack a
+message when your processing of that message *has completed*. When you ack
+a message, you are telling Pub/Sub that you do not need to see it again.
+
+It might be tempting to ack messages immediately on receipt. While there
+are valid use cases for this, in general it is unwise. The reason why: If
+there is some error or edge case in your processing logic, and processing
+of the message fails, you will have already told Pub/Sub that you successfully
+processed the message. By contrast, if you ack only upon completion, then
+Pub/Sub will eventually re-deliver the unacknowledged message.
+
+It is also possible to **nack** a message, which is the opposite. When you
+nack, it tells Pub/Sub that you are unable or unwilling to deal with the
+message, and that the service should redeliver it.
+
+
+API Reference
+-------------
+
+.. toctree::
+ :maxdepth: 2
+
+ api/client
+ api/message
+ api/futures
+ api/pagers
+ api/scheduler
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/types.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/types.rst
new file mode 100644
index 000000000000..87c987571766
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/docs/pubsub/types.rst
@@ -0,0 +1,5 @@
+Pub/Sub Client Types
+====================
+
+.. automodule:: google.cloud.pubsub_v1.types
+ :members:
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/__init__.py
new file mode 100644
index 000000000000..9a1b64a6d586
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/__init__.py
@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+try:
+ import pkg_resources
+
+ pkg_resources.declare_namespace(__name__)
+except ImportError:
+ import pkgutil
+
+ __path__ = pkgutil.extend_path(__path__, __name__)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/__init__.py
new file mode 100644
index 000000000000..e1f8a4d20fd1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/__init__.py
@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import List
+
+try:
+ import pkg_resources
+
+ pkg_resources.declare_namespace(__name__)
+except ImportError:
+ import pkgutil
+
+ __path__: List[str] = pkgutil.extend_path(__path__, __name__) # type: ignore
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub/__init__.py
new file mode 100644
index 000000000000..2a6994231cfe
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub/__init__.py
@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from __future__ import absolute_import
+
+from google.cloud.pubsub_v1 import PublisherClient
+from google.cloud.pubsub_v1 import SubscriberClient
+from google.cloud.pubsub_v1 import SchemaServiceClient
+from google.cloud.pubsub_v1 import types
+
+
+__all__ = (
+ "types",
+ "PublisherClient",
+ "SubscriberClient",
+ "SchemaServiceClient",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/__init__.py
new file mode 100644
index 000000000000..99bc3e9c8503
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/__init__.py
@@ -0,0 +1,35 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+from google.cloud.pubsub_v1 import types
+from google.cloud.pubsub_v1 import publisher
+from google.cloud.pubsub_v1 import subscriber
+from google.pubsub_v1.services import schema_service
+
+
+class PublisherClient(publisher.Client):
+ __doc__ = publisher.Client.__doc__
+
+
+class SubscriberClient(subscriber.Client):
+ __doc__ = subscriber.Client.__doc__
+
+
+class SchemaServiceClient(schema_service.client.SchemaServiceClient):
+ __doc__ = schema_service.client.SchemaServiceClient.__doc__
+
+
+__all__ = ("types", "PublisherClient", "SubscriberClient", "SchemaServiceClient")
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/exceptions.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/exceptions.py
new file mode 100644
index 000000000000..5ab750d0477c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/exceptions.py
@@ -0,0 +1,20 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+from concurrent.futures import TimeoutError
+
+
+__all__ = ("TimeoutError",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
new file mode 100644
index 000000000000..5527d21d0683
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
@@ -0,0 +1,56 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import concurrent.futures
+from typing import Any, NoReturn, Optional
+
+import google.api_core.future
+
+
+class Future(concurrent.futures.Future, google.api_core.future.Future):
+ """Encapsulation of the asynchronous execution of an action.
+
+ This object is returned from asychronous Pub/Sub calls, and is the
+ interface to determine the status of those calls.
+
+ This object should not be created directly, but is returned by other
+ methods in this library.
+ """
+
+ def running(self) -> bool:
+ """Return ``True`` if the associated Pub/Sub action has not yet completed."""
+ return not self.done()
+
+ def set_running_or_notify_cancel(self) -> NoReturn:
+ raise NotImplementedError(
+ "Only used by executors from `concurrent.futures` package."
+ )
+
+ def set_result(self, result: Any):
+ """Set the return value of work associated with the future.
+
+ Do not use this method, it should only be used internally by the library and its
+ unit tests.
+ """
+ return super().set_result(result=result)
+
+ def set_exception(self, exception: Optional[BaseException]):
+ """Set the result of the future as being the given exception.
+
+ Do not use this method, it should only be used internally by the library and its
+ unit tests.
+ """
+ return super().set_exception(exception=exception)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/proto/pubsub.proto b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/proto/pubsub.proto
new file mode 100644
index 000000000000..716c7ba05cb4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/proto/pubsub.proto
@@ -0,0 +1,1344 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.pubsub.v1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
+import "google/protobuf/timestamp.proto";
+import "google/pubsub/v1/schema.proto";
+
+option cc_enable_arenas = true;
+option csharp_namespace = "Google.Cloud.PubSub.V1";
+option go_package = "google.golang.org/genproto/googleapis/pubsub/v1;pubsub";
+option java_multiple_files = true;
+option java_outer_classname = "PubsubProto";
+option java_package = "com.google.pubsub.v1";
+option php_namespace = "Google\\Cloud\\PubSub\\V1";
+option ruby_package = "Google::Cloud::PubSub::V1";
+
+// The service that an application uses to manipulate topics, and to send
+// messages to a topic.
+service Publisher {
+ option (google.api.default_host) = "pubsub.googleapis.com";
+ option (google.api.oauth_scopes) =
+ "https://www.googleapis.com/auth/cloud-platform,"
+ "https://www.googleapis.com/auth/pubsub";
+
+ // Creates the given topic with the given name. See the [resource name rules]
+ // (https://cloud.google.com/pubsub/docs/admin#resource_names).
+ rpc CreateTopic(Topic) returns (Topic) {
+ option (google.api.http) = {
+ put: "/v1/{name=projects/*/topics/*}"
+ body: "*"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Updates an existing topic. Note that certain properties of a
+ // topic are not modifiable.
+ rpc UpdateTopic(UpdateTopicRequest) returns (Topic) {
+ option (google.api.http) = {
+ patch: "/v1/{topic.name=projects/*/topics/*}"
+ body: "*"
+ };
+ }
+
+ // Adds one or more messages to the topic. Returns `NOT_FOUND` if the topic
+ // does not exist.
+ rpc Publish(PublishRequest) returns (PublishResponse) {
+ option (google.api.http) = {
+ post: "/v1/{topic=projects/*/topics/*}:publish"
+ body: "*"
+ };
+ option (google.api.method_signature) = "topic,messages";
+ }
+
+ // Gets the configuration of a topic.
+ rpc GetTopic(GetTopicRequest) returns (Topic) {
+ option (google.api.http) = {
+ get: "/v1/{topic=projects/*/topics/*}"
+ };
+ option (google.api.method_signature) = "topic";
+ }
+
+ // Lists matching topics.
+ rpc ListTopics(ListTopicsRequest) returns (ListTopicsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{project=projects/*}/topics"
+ };
+ option (google.api.method_signature) = "project";
+ }
+
+ // Lists the names of the attached subscriptions on this topic.
+ rpc ListTopicSubscriptions(ListTopicSubscriptionsRequest)
+ returns (ListTopicSubscriptionsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{topic=projects/*/topics/*}/subscriptions"
+ };
+ option (google.api.method_signature) = "topic";
+ }
+
+ // Lists the names of the snapshots on this topic. Snapshots are used in
+ // [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
+ // which allow you to manage message acknowledgments in bulk. That is, you can
+ // set the acknowledgment state of messages in an existing subscription to the
+ // state captured by a snapshot.
+ rpc ListTopicSnapshots(ListTopicSnapshotsRequest)
+ returns (ListTopicSnapshotsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{topic=projects/*/topics/*}/snapshots"
+ };
+ option (google.api.method_signature) = "topic";
+ }
+
+ // Deletes the topic with the given name. Returns `NOT_FOUND` if the topic
+ // does not exist. After a topic is deleted, a new topic may be created with
+ // the same name; this is an entirely new topic with none of the old
+ // configuration or subscriptions. Existing subscriptions to this topic are
+ // not deleted, but their `topic` field is set to `_deleted-topic_`.
+ rpc DeleteTopic(DeleteTopicRequest) returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v1/{topic=projects/*/topics/*}"
+ };
+ option (google.api.method_signature) = "topic";
+ }
+
+ // Detaches a subscription from this topic. All messages retained in the
+ // subscription are dropped. Subsequent `Pull` and `StreamingPull` requests
+ // will return FAILED_PRECONDITION. If the subscription is a push
+ // subscription, pushes to the endpoint will stop.
+ rpc DetachSubscription(DetachSubscriptionRequest)
+ returns (DetachSubscriptionResponse) {
+ option (google.api.http) = {
+ post: "/v1/{subscription=projects/*/subscriptions/*}:detach"
+ };
+ }
+}
+
+// A policy constraining the storage of messages published to the topic.
+message MessageStoragePolicy {
+ // A list of IDs of GCP regions where messages that are published to the topic
+ // may be persisted in storage. Messages published by publishers running in
+ // non-allowed GCP regions (or running outside of GCP altogether) will be
+ // routed for storage in one of the allowed regions. An empty list means that
+ // no regions are allowed, and is not a valid configuration.
+ repeated string allowed_persistence_regions = 1;
+}
+
+// Settings for validating messages published against a schema.
+message SchemaSettings {
+ // Required. The name of the schema that messages published should be
+ // validated against. Format is `projects/{project}/schemas/{schema}`. The
+ // value of this field will be `_deleted-schema_` if the schema has been
+ // deleted.
+ string schema = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+ ];
+
+ // The encoding of messages validated against `schema`.
+ Encoding encoding = 2;
+}
+
+// A topic resource.
+message Topic {
+ option (google.api.resource) = {
+ type: "pubsub.googleapis.com/Topic"
+ pattern: "projects/{project}/topics/{topic}"
+ pattern: "_deleted-topic_"
+ };
+
+ // Required. The name of the topic. It must have the format
+ // `"projects/{project}/topics/{topic}"`. `{topic}` must start with a letter,
+ // and contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
+ // underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
+ // signs (`%`). It must be between 3 and 255 characters in length, and it
+ // must not start with `"goog"`.
+ string name = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // See [Creating and managing labels]
+ // (https://cloud.google.com/pubsub/docs/labels).
+ map labels = 2;
+
+ // Policy constraining the set of Google Cloud Platform regions where messages
+ // published to the topic may be stored. If not present, then no constraints
+ // are in effect.
+ MessageStoragePolicy message_storage_policy = 3;
+
+ // The resource name of the Cloud KMS CryptoKey to be used to protect access
+ // to messages published on this topic.
+ //
+ // The expected format is `projects/*/locations/*/keyRings/*/cryptoKeys/*`.
+ string kms_key_name = 5;
+
+ // Settings for validating messages published against a schema.
+ SchemaSettings schema_settings = 6;
+
+ // Reserved for future use. This field is set only in responses from the
+ // server; it is ignored if it is set in any requests.
+ bool satisfies_pzs = 7;
+
+ // Indicates the minimum duration to retain a message after it is published to
+ // the topic. If this field is set, messages published to the topic in the
+ // last `message_retention_duration` are always available to subscribers. For
+ // instance, it allows any attached subscription to [seek to a
+ // timestamp](https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)
+ // that is up to `message_retention_duration` in the past. If this field is
+ // not set, message retention is controlled by settings on individual
+ // subscriptions. Cannot be more than 7 days or less than 10 minutes.
+ google.protobuf.Duration message_retention_duration = 8;
+}
+
+// A message that is published by publishers and consumed by subscribers. The
+// message must contain either a non-empty data field or at least one attribute.
+// Note that client libraries represent this object differently
+// depending on the language. See the corresponding [client library
+// documentation](https://cloud.google.com/pubsub/docs/reference/libraries) for
+// more information. See [quotas and limits]
+// (https://cloud.google.com/pubsub/quotas) for more information about message
+// limits.
+message PubsubMessage {
+ // The message data field. If this field is empty, the message must contain
+ // at least one attribute.
+ bytes data = 1;
+
+ // Attributes for this message. If this field is empty, the message must
+ // contain non-empty data. This can be used to filter messages on the
+ // subscription.
+ map attributes = 2;
+
+ // ID of this message, assigned by the server when the message is published.
+ // Guaranteed to be unique within the topic. This value may be read by a
+ // subscriber that receives a `PubsubMessage` via a `Pull` call or a push
+ // delivery. It must not be populated by the publisher in a `Publish` call.
+ string message_id = 3;
+
+ // The time at which the message was published, populated by the server when
+ // it receives the `Publish` call. It must not be populated by the
+ // publisher in a `Publish` call.
+ google.protobuf.Timestamp publish_time = 4;
+
+ // If non-empty, identifies related messages for which publish order should be
+ // respected. If a `Subscription` has `enable_message_ordering` set to `true`,
+ // messages published with the same non-empty `ordering_key` value will be
+ // delivered to subscribers in the order in which they are received by the
+ // Pub/Sub system. All `PubsubMessage`s published in a given `PublishRequest`
+ // must specify the same `ordering_key` value.
+ string ordering_key = 5;
+}
+
+// Request for the GetTopic method.
+message GetTopicRequest {
+ // Required. The name of the topic to get.
+ // Format is `projects/{project}/topics/{topic}`.
+ string topic = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Topic" }
+ ];
+}
+
+// Request for the UpdateTopic method.
+message UpdateTopicRequest {
+ // Required. The updated topic object.
+ Topic topic = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. Indicates which fields in the provided topic to update. Must be
+ // specified and non-empty. Note that if `update_mask` contains
+ // "message_storage_policy" but the `message_storage_policy` is not set in
+ // the `topic` provided above, then the updated value is determined by the
+ // policy configured at the project or organization level.
+ google.protobuf.FieldMask update_mask = 2
+ [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for the Publish method.
+message PublishRequest {
+ // Required. The messages in the request will be published on this topic.
+ // Format is `projects/{project}/topics/{topic}`.
+ string topic = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Topic" }
+ ];
+
+ // Required. The messages to publish.
+ repeated PubsubMessage messages = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Response for the `Publish` method.
+message PublishResponse {
+ // The server-assigned ID of each published message, in the same order as
+ // the messages in the request. IDs are guaranteed to be unique within
+ // the topic.
+ repeated string message_ids = 1;
+}
+
+// Request for the `ListTopics` method.
+message ListTopicsRequest {
+ // Required. The name of the project in which to list topics.
+ // Format is `projects/{project-id}`.
+ string project = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "cloudresourcemanager.googleapis.com/Project"
+ }
+ ];
+
+ // Maximum number of topics to return.
+ int32 page_size = 2;
+
+ // The value returned by the last `ListTopicsResponse`; indicates that this is
+ // a continuation of a prior `ListTopics` call, and that the system should
+ // return the next page of data.
+ string page_token = 3;
+}
+
+// Response for the `ListTopics` method.
+message ListTopicsResponse {
+ // The resulting topics.
+ repeated Topic topics = 1;
+
+ // If not empty, indicates that there may be more topics that match the
+ // request; this value should be passed in a new `ListTopicsRequest`.
+ string next_page_token = 2;
+}
+
+// Request for the `ListTopicSubscriptions` method.
+message ListTopicSubscriptionsRequest {
+ // Required. The name of the topic that subscriptions are attached to.
+ // Format is `projects/{project}/topics/{topic}`.
+ string topic = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Topic" }
+ ];
+
+ // Maximum number of subscription names to return.
+ int32 page_size = 2;
+
+ // The value returned by the last `ListTopicSubscriptionsResponse`; indicates
+ // that this is a continuation of a prior `ListTopicSubscriptions` call, and
+ // that the system should return the next page of data.
+ string page_token = 3;
+}
+
+// Response for the `ListTopicSubscriptions` method.
+message ListTopicSubscriptionsResponse {
+ // The names of subscriptions attached to the topic specified in the request.
+ repeated string subscriptions = 1 [(google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }];
+
+ // If not empty, indicates that there may be more subscriptions that match
+ // the request; this value should be passed in a new
+ // `ListTopicSubscriptionsRequest` to get more subscriptions.
+ string next_page_token = 2;
+}
+
+// Request for the `ListTopicSnapshots` method.
+message ListTopicSnapshotsRequest {
+ // Required. The name of the topic that snapshots are attached to.
+ // Format is `projects/{project}/topics/{topic}`.
+ string topic = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Topic" }
+ ];
+
+ // Maximum number of snapshot names to return.
+ int32 page_size = 2;
+
+ // The value returned by the last `ListTopicSnapshotsResponse`; indicates
+ // that this is a continuation of a prior `ListTopicSnapshots` call, and
+ // that the system should return the next page of data.
+ string page_token = 3;
+}
+
+// Response for the `ListTopicSnapshots` method.
+message ListTopicSnapshotsResponse {
+ // The names of the snapshots that match the request.
+ repeated string snapshots = 1;
+
+ // If not empty, indicates that there may be more snapshots that match
+ // the request; this value should be passed in a new
+ // `ListTopicSnapshotsRequest` to get more snapshots.
+ string next_page_token = 2;
+}
+
+// Request for the `DeleteTopic` method.
+message DeleteTopicRequest {
+ // Required. Name of the topic to delete.
+ // Format is `projects/{project}/topics/{topic}`.
+ string topic = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Topic" }
+ ];
+}
+
+// Request for the DetachSubscription method.
+message DetachSubscriptionRequest {
+ // Required. The subscription to detach.
+ // Format is `projects/{project}/subscriptions/{subscription}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+}
+
+// Response for the DetachSubscription method.
+// Reserved for future use.
+message DetachSubscriptionResponse {}
+
+// The service that an application uses to manipulate subscriptions and to
+// consume messages from a subscription via the `Pull` method or by
+// establishing a bi-directional stream using the `StreamingPull` method.
+service Subscriber {
+ option (google.api.default_host) = "pubsub.googleapis.com";
+ option (google.api.oauth_scopes) =
+ "https://www.googleapis.com/auth/cloud-platform,"
+ "https://www.googleapis.com/auth/pubsub";
+
+ // Creates a subscription to a given topic. See the [resource name rules]
+ // (https://cloud.google.com/pubsub/docs/admin#resource_names).
+ // If the subscription already exists, returns `ALREADY_EXISTS`.
+ // If the corresponding topic doesn't exist, returns `NOT_FOUND`.
+ //
+ // If the name is not provided in the request, the server will assign a random
+ // name for this subscription on the same project as the topic, conforming
+ // to the [resource name format]
+ // (https://cloud.google.com/pubsub/docs/admin#resource_names). The generated
+ // name is populated in the returned Subscription object. Note that for REST
+ // API requests, you must specify a name in the request.
+ rpc CreateSubscription(Subscription) returns (Subscription) {
+ option (google.api.http) = {
+ put: "/v1/{name=projects/*/subscriptions/*}"
+ body: "*"
+ };
+ option (google.api.method_signature) =
+ "name,topic,push_config,ack_deadline_seconds";
+ }
+
+ // Gets the configuration details of a subscription.
+ rpc GetSubscription(GetSubscriptionRequest) returns (Subscription) {
+ option (google.api.http) = {
+ get: "/v1/{subscription=projects/*/subscriptions/*}"
+ };
+ option (google.api.method_signature) = "subscription";
+ }
+
+ // Updates an existing subscription. Note that certain properties of a
+ // subscription, such as its topic, are not modifiable.
+ rpc UpdateSubscription(UpdateSubscriptionRequest) returns (Subscription) {
+ option (google.api.http) = {
+ patch: "/v1/{subscription.name=projects/*/subscriptions/*}"
+ body: "*"
+ };
+ }
+
+ // Lists matching subscriptions.
+ rpc ListSubscriptions(ListSubscriptionsRequest)
+ returns (ListSubscriptionsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{project=projects/*}/subscriptions"
+ };
+ option (google.api.method_signature) = "project";
+ }
+
+ // Deletes an existing subscription. All messages retained in the subscription
+ // are immediately dropped. Calls to `Pull` after deletion will return
+ // `NOT_FOUND`. After a subscription is deleted, a new one may be created with
+ // the same name, but the new one has no association with the old
+ // subscription or its topic unless the same topic is specified.
+ rpc DeleteSubscription(DeleteSubscriptionRequest)
+ returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v1/{subscription=projects/*/subscriptions/*}"
+ };
+ option (google.api.method_signature) = "subscription";
+ }
+
+ // Modifies the ack deadline for a specific message. This method is useful
+ // to indicate that more time is needed to process a message by the
+ // subscriber, or to make the message available for redelivery if the
+ // processing was interrupted. Note that this does not modify the
+ // subscription-level `ackDeadlineSeconds` used for subsequent messages.
+ rpc ModifyAckDeadline(ModifyAckDeadlineRequest)
+ returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ post: "/v1/{subscription=projects/*/subscriptions/*}:modifyAckDeadline"
+ body: "*"
+ };
+ option (google.api.method_signature) =
+ "subscription,ack_ids,ack_deadline_seconds";
+ }
+
+ // Acknowledges the messages associated with the `ack_ids` in the
+ // `AcknowledgeRequest`. The Pub/Sub system can remove the relevant messages
+ // from the subscription.
+ //
+ // Acknowledging a message whose ack deadline has expired may succeed,
+ // but such a message may be redelivered later. Acknowledging a message more
+ // than once will not result in an error.
+ rpc Acknowledge(AcknowledgeRequest) returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ post: "/v1/{subscription=projects/*/subscriptions/*}:acknowledge"
+ body: "*"
+ };
+ option (google.api.method_signature) = "subscription,ack_ids";
+ }
+
+ // Pulls messages from the server. The server may return `UNAVAILABLE` if
+ // there are too many concurrent pull requests pending for the given
+ // subscription.
+ rpc Pull(PullRequest) returns (PullResponse) {
+ option (google.api.http) = {
+ post: "/v1/{subscription=projects/*/subscriptions/*}:pull"
+ body: "*"
+ };
+ option (google.api.method_signature) =
+ "subscription,return_immediately,max_messages";
+ option (google.api.method_signature) = "subscription,max_messages";
+ }
+
+ // Establishes a stream with the server, which sends messages down to the
+ // client. The client streams acknowledgements and ack deadline modifications
+ // back to the server. The server will close the stream and return the status
+ // on any error. The server may close the stream with status `UNAVAILABLE` to
+ // reassign server-side resources, in which case, the client should
+ // re-establish the stream. Flow control can be achieved by configuring the
+ // underlying RPC channel.
+ rpc StreamingPull(stream StreamingPullRequest)
+ returns (stream StreamingPullResponse) {}
+
+ // Modifies the `PushConfig` for a specified subscription.
+ //
+ // This may be used to change a push subscription to a pull one (signified by
+ // an empty `PushConfig`) or vice versa, or change the endpoint URL and other
+ // attributes of a push subscription. Messages will accumulate for delivery
+ // continuously through the call regardless of changes to the `PushConfig`.
+ rpc ModifyPushConfig(ModifyPushConfigRequest)
+ returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ post: "/v1/{subscription=projects/*/subscriptions/*}:modifyPushConfig"
+ body: "*"
+ };
+ option (google.api.method_signature) = "subscription,push_config";
+ }
+
+ // Gets the configuration details of a snapshot. Snapshots are used in
+ // Seek
+ // operations, which allow you to manage message acknowledgments in bulk. That
+ // is, you can set the acknowledgment state of messages in an existing
+ // subscription to the state captured by a snapshot.
+ rpc GetSnapshot(GetSnapshotRequest) returns (Snapshot) {
+ option (google.api.http) = {
+ get: "/v1/{snapshot=projects/*/snapshots/*}"
+ };
+ option (google.api.method_signature) = "snapshot";
+ }
+
+ // Lists the existing snapshots. Snapshots are used in [Seek](
+ // https://cloud.google.com/pubsub/docs/replay-overview) operations, which
+ // allow you to manage message acknowledgments in bulk. That is, you can set
+ // the acknowledgment state of messages in an existing subscription to the
+ // state captured by a snapshot.
+ rpc ListSnapshots(ListSnapshotsRequest) returns (ListSnapshotsResponse) {
+ option (google.api.http) = {
+ get: "/v1/{project=projects/*}/snapshots"
+ };
+ option (google.api.method_signature) = "project";
+ }
+
+ // Creates a snapshot from the requested subscription. Snapshots are used in
+ // [Seek](https://cloud.google.com/pubsub/docs/replay-overview) operations,
+ // which allow you to manage message acknowledgments in bulk. That is, you can
+ // set the acknowledgment state of messages in an existing subscription to the
+ // state captured by a snapshot.
+ // If the snapshot already exists, returns `ALREADY_EXISTS`.
+ // If the requested subscription doesn't exist, returns `NOT_FOUND`.
+ // If the backlog in the subscription is too old -- and the resulting snapshot
+ // would expire in less than 1 hour -- then `FAILED_PRECONDITION` is returned.
+ // See also the `Snapshot.expire_time` field. If the name is not provided in
+ // the request, the server will assign a random
+ // name for this snapshot on the same project as the subscription, conforming
+ // to the [resource name format]
+ // (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ // generated name is populated in the returned Snapshot object. Note that for
+ // REST API requests, you must specify a name in the request.
+ rpc CreateSnapshot(CreateSnapshotRequest) returns (Snapshot) {
+ option (google.api.http) = {
+ put: "/v1/{name=projects/*/snapshots/*}"
+ body: "*"
+ };
+ option (google.api.method_signature) = "name,subscription";
+ }
+
+ // Updates an existing snapshot. Snapshots are used in
+ // Seek
+ // operations, which allow
+ // you to manage message acknowledgments in bulk. That is, you can set the
+ // acknowledgment state of messages in an existing subscription to the state
+ // captured by a snapshot.
+ rpc UpdateSnapshot(UpdateSnapshotRequest) returns (Snapshot) {
+ option (google.api.http) = {
+ patch: "/v1/{snapshot.name=projects/*/snapshots/*}"
+ body: "*"
+ };
+ }
+
+ // Removes an existing snapshot. Snapshots are used in [Seek]
+ // (https://cloud.google.com/pubsub/docs/replay-overview) operations, which
+ // allow you to manage message acknowledgments in bulk. That is, you can set
+ // the acknowledgment state of messages in an existing subscription to the
+ // state captured by a snapshot.
+ // When the snapshot is deleted, all messages retained in the snapshot
+ // are immediately dropped. After a snapshot is deleted, a new one may be
+ // created with the same name, but the new one has no association with the old
+ // snapshot or its subscription, unless the same subscription is specified.
+ rpc DeleteSnapshot(DeleteSnapshotRequest) returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v1/{snapshot=projects/*/snapshots/*}"
+ };
+ option (google.api.method_signature) = "snapshot";
+ }
+
+ // Seeks an existing subscription to a point in time or to a given snapshot,
+ // whichever is provided in the request. Snapshots are used in [Seek]
+ // (https://cloud.google.com/pubsub/docs/replay-overview) operations, which
+ // allow you to manage message acknowledgments in bulk. That is, you can set
+ // the acknowledgment state of messages in an existing subscription to the
+ // state captured by a snapshot. Note that both the subscription and the
+ // snapshot must be on the same topic.
+ rpc Seek(SeekRequest) returns (SeekResponse) {
+ option (google.api.http) = {
+ post: "/v1/{subscription=projects/*/subscriptions/*}:seek"
+ body: "*"
+ };
+ }
+}
+
+// A subscription resource.
+message Subscription {
+ option (google.api.resource) = {
+ type: "pubsub.googleapis.com/Subscription"
+ pattern: "projects/{project}/subscriptions/{subscription}"
+ };
+
+ // Required. The name of the subscription. It must have the format
+ // `"projects/{project}/subscriptions/{subscription}"`. `{subscription}` must
+ // start with a letter, and contain only letters (`[A-Za-z]`), numbers
+ // (`[0-9]`), dashes (`-`), underscores (`_`), periods (`.`), tildes (`~`),
+ // plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
+ // in length, and it must not start with `"goog"`.
+ string name = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The name of the topic from which this subscription is receiving
+ // messages. Format is `projects/{project}/topics/{topic}`. The value of this
+ // field will be `_deleted-topic_` if the topic has been deleted.
+ string topic = 2 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Topic" }
+ ];
+
+ // If push delivery is used with this subscription, this field is
+ // used to configure it. An empty `pushConfig` signifies that the subscriber
+ // will pull and ack messages using API methods.
+ PushConfig push_config = 4;
+
+ // The approximate amount of time (on a best-effort basis) Pub/Sub waits for
+ // the subscriber to acknowledge receipt before resending the message. In the
+ // interval after the message is delivered and before it is acknowledged, it
+ // is considered to be outstanding . During that time period, the
+ // message will not be redelivered (on a best-effort basis).
+ //
+ // For pull subscriptions, this value is used as the initial value for the ack
+ // deadline. To override this value for a given message, call
+ // `ModifyAckDeadline` with the corresponding `ack_id` if using
+ // non-streaming pull or send the `ack_id` in a
+ // `StreamingModifyAckDeadlineRequest` if using streaming pull.
+ // The minimum custom deadline you can specify is 10 seconds.
+ // The maximum custom deadline you can specify is 600 seconds (10 minutes).
+ // If this parameter is 0, a default value of 10 seconds is used.
+ //
+ // For push delivery, this value is also used to set the request timeout for
+ // the call to the push endpoint.
+ //
+ // If the subscriber never acknowledges the message, the Pub/Sub
+ // system will eventually redeliver the message.
+ int32 ack_deadline_seconds = 5;
+
+ // Indicates whether to retain acknowledged messages. If true, then
+ // messages are not expunged from the subscription's backlog, even if they are
+ // acknowledged, until they fall out of the `message_retention_duration`
+ // window. This must be true if you would like to [Seek to a timestamp]
+ // (https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time).
+ bool retain_acked_messages = 7;
+
+ // How long to retain unacknowledged messages in the subscription's backlog,
+ // from the moment a message is published.
+ // If `retain_acked_messages` is true, then this also configures the retention
+ // of acknowledged messages, and thus configures how far back in time a `Seek`
+ // can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
+ // minutes.
+ google.protobuf.Duration message_retention_duration = 8;
+
+ // See Creating and
+ // managing labels .
+ map labels = 9;
+
+ // If true, messages published with the same `ordering_key` in `PubsubMessage`
+ // will be delivered to the subscribers in the order in which they
+ // are received by the Pub/Sub system. Otherwise, they may be delivered in
+ // any order.
+ bool enable_message_ordering = 10;
+
+ // A policy that specifies the conditions for this subscription's expiration.
+ // A subscription is considered active as long as any connected subscriber is
+ // successfully consuming messages from the subscription or is issuing
+ // operations on the subscription. If `expiration_policy` is not set, a
+ // *default policy* with `ttl` of 31 days will be used. The minimum allowed
+ // value for `expiration_policy.ttl` is 1 day.
+ ExpirationPolicy expiration_policy = 11;
+
+ // An expression written in the Pub/Sub [filter
+ // language](https://cloud.google.com/pubsub/docs/filtering). If non-empty,
+ // then only `PubsubMessage`s whose `attributes` field matches the filter are
+ // delivered on this subscription. If empty, then no messages are filtered
+ // out.
+ string filter = 12;
+
+ // A policy that specifies the conditions for dead lettering messages in
+ // this subscription. If dead_letter_policy is not set, dead lettering
+ // is disabled.
+ //
+ // The Cloud Pub/Sub service account associated with this subscriptions's
+ // parent project (i.e.,
+ // service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ // permission to Acknowledge() messages on this subscription.
+ DeadLetterPolicy dead_letter_policy = 13;
+
+ // A policy that specifies how Pub/Sub retries message delivery for this
+ // subscription.
+ //
+ // If not set, the default retry policy is applied. This generally implies
+ // that messages will be retried as soon as possible for healthy subscribers.
+ // RetryPolicy will be triggered on NACKs or acknowledgement deadline
+ // exceeded events for a given message.
+ RetryPolicy retry_policy = 14;
+
+ // Indicates whether the subscription is detached from its topic. Detached
+ // subscriptions don't receive messages from their topic and don't retain any
+ // backlog. `Pull` and `StreamingPull` requests will return
+ // FAILED_PRECONDITION. If the subscription is a push subscription, pushes to
+ // the endpoint will not be made.
+ bool detached = 15;
+
+ // Output only. Indicates the minimum duration for which a message is retained
+ // after it is published to the subscription's topic. If this field is set,
+ // messages published to the subscription's topic in the last
+ // `topic_message_retention_duration` are always available to subscribers. See
+ // the `message_retention_duration` field in `Topic`. This field is set only
+ // in responses from the server; it is ignored if it is set in any requests.
+ google.protobuf.Duration topic_message_retention_duration = 17
+ [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// A policy that specifies how Cloud Pub/Sub retries message delivery.
+//
+// Retry delay will be exponential based on provided minimum and maximum
+// backoffs. https://en.wikipedia.org/wiki/Exponential_backoff.
+//
+// RetryPolicy will be triggered on NACKs or acknowledgement deadline exceeded
+// events for a given message.
+//
+// Retry Policy is implemented on a best effort basis. At times, the delay
+// between consecutive deliveries may not match the configuration. That is,
+// delay can be more or less than configured backoff.
+message RetryPolicy {
+ // The minimum delay between consecutive deliveries of a given message.
+ // Value should be between 0 and 600 seconds. Defaults to 10 seconds.
+ google.protobuf.Duration minimum_backoff = 1;
+
+ // The maximum delay between consecutive deliveries of a given message.
+ // Value should be between 0 and 600 seconds. Defaults to 600 seconds.
+ google.protobuf.Duration maximum_backoff = 2;
+}
+
+// Dead lettering is done on a best effort basis. The same message might be
+// dead lettered multiple times.
+//
+// If validation on any of the fields fails at subscription creation/updation,
+// the create/update subscription request will fail.
+message DeadLetterPolicy {
+ // The name of the topic to which dead letter messages should be published.
+ // Format is `projects/{project}/topics/{topic}`.The Cloud Pub/Sub service
+ // account associated with the enclosing subscription's parent project (i.e.,
+ // service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
+ // permission to Publish() to this topic.
+ //
+ // The operation will fail if the topic does not exist.
+ // Users should ensure that there is a subscription attached to this topic
+ // since messages published to a topic with no subscriptions are lost.
+ string dead_letter_topic = 1;
+
+ // The maximum number of delivery attempts for any message. The value must be
+ // between 5 and 100.
+ //
+ // The number of delivery attempts is defined as 1 + (the sum of number of
+ // NACKs and number of times the acknowledgement deadline has been exceeded
+ // for the message).
+ //
+ // A NACK is any call to ModifyAckDeadline with a 0 deadline. Note that
+ // client libraries may automatically extend ack_deadlines.
+ //
+ // This field will be honored on a best effort basis.
+ //
+ // If this parameter is 0, a default value of 5 is used.
+ int32 max_delivery_attempts = 2;
+}
+
+// A policy that specifies the conditions for resource expiration (i.e.,
+// automatic resource deletion).
+message ExpirationPolicy {
+ // Specifies the "time-to-live" duration for an associated resource. The
+ // resource expires if it is not active for a period of `ttl`. The definition
+ // of "activity" depends on the type of the associated resource. The minimum
+ // and maximum allowed values for `ttl` depend on the type of the associated
+ // resource, as well. If `ttl` is not set, the associated resource never
+ // expires.
+ google.protobuf.Duration ttl = 1;
+}
+
+// Configuration for a push delivery endpoint.
+message PushConfig {
+ // Contains information needed for generating an
+ // [OpenID Connect
+ // token](https://developers.google.com/identity/protocols/OpenIDConnect).
+ message OidcToken {
+ // [Service account
+ // email](https://cloud.google.com/iam/docs/service-accounts)
+ // to be used for generating the OIDC token. The caller (for
+ // CreateSubscription, UpdateSubscription, and ModifyPushConfig RPCs) must
+ // have the iam.serviceAccounts.actAs permission for the service account.
+ string service_account_email = 1;
+
+ // Audience to be used when generating OIDC token. The audience claim
+ // identifies the recipients that the JWT is intended for. The audience
+ // value is a single case-sensitive string. Having multiple values (array)
+ // for the audience field is not supported. More info about the OIDC JWT
+ // token audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3
+ // Note: if not specified, the Push endpoint URL will be used.
+ string audience = 2;
+ }
+
+ // A URL locating the endpoint to which messages should be pushed.
+ // For example, a Webhook endpoint might use `https://example.com/push`.
+ string push_endpoint = 1;
+
+ // Endpoint configuration attributes that can be used to control different
+ // aspects of the message delivery.
+ //
+ // The only currently supported attribute is `x-goog-version`, which you can
+ // use to change the format of the pushed message. This attribute
+ // indicates the version of the data expected by the endpoint. This
+ // controls the shape of the pushed message (i.e., its fields and metadata).
+ //
+ // If not present during the `CreateSubscription` call, it will default to
+ // the version of the Pub/Sub API used to make such call. If not present in a
+ // `ModifyPushConfig` call, its value will not be changed. `GetSubscription`
+ // calls will always return a valid version, even if the subscription was
+ // created without this attribute.
+ //
+ // The only supported values for the `x-goog-version` attribute are:
+ //
+ // * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub API.
+ // * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub API.
+ //
+ // For example:
+ // attributes { "x-goog-version": "v1" } attributes = 2;
+
+ // An authentication method used by push endpoints to verify the source of
+ // push requests. This can be used with push endpoints that are private by
+ // default to allow requests only from the Cloud Pub/Sub system, for example.
+ // This field is optional and should be set only by users interested in
+ // authenticated push.
+ oneof authentication_method {
+ // If specified, Pub/Sub will generate and attach an OIDC JWT token as an
+ // `Authorization` header in the HTTP request for every pushed message.
+ OidcToken oidc_token = 3;
+ }
+}
+
+// A message and its corresponding acknowledgment ID.
+message ReceivedMessage {
+ // This ID can be used to acknowledge the received message.
+ string ack_id = 1;
+
+ // The message.
+ PubsubMessage message = 2;
+
+ // The approximate number of times that Cloud Pub/Sub has attempted to deliver
+ // the associated message to a subscriber.
+ //
+ // More precisely, this is 1 + (number of NACKs) +
+ // (number of ack_deadline exceeds) for this message.
+ //
+ // A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
+ // exceeds event is whenever a message is not acknowledged within
+ // ack_deadline. Note that ack_deadline is initially
+ // Subscription.ackDeadlineSeconds, but may get extended automatically by
+ // the client library.
+ //
+ // Upon the first delivery of a given message, `delivery_attempt` will have a
+ // value of 1. The value is calculated at best effort and is approximate.
+ //
+ // If a DeadLetterPolicy is not set on the subscription, this will be 0.
+ int32 delivery_attempt = 3;
+}
+
+// Request for the GetSubscription method.
+message GetSubscriptionRequest {
+ // Required. The name of the subscription to get.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+}
+
+// Request for the UpdateSubscription method.
+message UpdateSubscriptionRequest {
+ // Required. The updated subscription object.
+ Subscription subscription = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. Indicates which fields in the provided subscription to update.
+ // Must be specified and non-empty.
+ google.protobuf.FieldMask update_mask = 2
+ [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for the `ListSubscriptions` method.
+message ListSubscriptionsRequest {
+ // Required. The name of the project in which to list subscriptions.
+ // Format is `projects/{project-id}`.
+ string project = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "cloudresourcemanager.googleapis.com/Project"
+ }
+ ];
+
+ // Maximum number of subscriptions to return.
+ int32 page_size = 2;
+
+ // The value returned by the last `ListSubscriptionsResponse`; indicates that
+ // this is a continuation of a prior `ListSubscriptions` call, and that the
+ // system should return the next page of data.
+ string page_token = 3;
+}
+
+// Response for the `ListSubscriptions` method.
+message ListSubscriptionsResponse {
+ // The subscriptions that match the request.
+ repeated Subscription subscriptions = 1;
+
+ // If not empty, indicates that there may be more subscriptions that match
+ // the request; this value should be passed in a new
+ // `ListSubscriptionsRequest` to get more subscriptions.
+ string next_page_token = 2;
+}
+
+// Request for the DeleteSubscription method.
+message DeleteSubscriptionRequest {
+ // Required. The subscription to delete.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+}
+
+// Request for the ModifyPushConfig method.
+message ModifyPushConfigRequest {
+ // Required. The name of the subscription.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+
+ // Required. The push configuration for future deliveries.
+ //
+ // An empty `pushConfig` indicates that the Pub/Sub system should
+ // stop pushing messages from the given subscription and allow
+ // messages to be pulled and acknowledged - effectively pausing
+ // the subscription if `Pull` or `StreamingPull` is not called.
+ PushConfig push_config = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for the `Pull` method.
+message PullRequest {
+ // Required. The subscription from which messages should be pulled.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+
+ // Optional. If this field set to true, the system will respond immediately
+ // even if it there are no messages available to return in the `Pull`
+ // response. Otherwise, the system may wait (for a bounded amount of time)
+ // until at least one message is available, rather than returning no messages.
+ // Warning: setting this field to `true` is discouraged because it adversely
+ // impacts the performance of `Pull` operations. We recommend that users do
+ // not set this field.
+ bool return_immediately = 2
+ [deprecated = true, (google.api.field_behavior) = OPTIONAL];
+
+ // Required. The maximum number of messages to return for this request. Must
+ // be a positive integer. The Pub/Sub system may return fewer than the number
+ // specified.
+ int32 max_messages = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Response for the `Pull` method.
+message PullResponse {
+ // Received Pub/Sub messages. The list will be empty if there are no more
+ // messages available in the backlog. For JSON, the response can be entirely
+ // empty. The Pub/Sub system may return fewer than the `maxMessages` requested
+ // even if there are more messages available in the backlog.
+ repeated ReceivedMessage received_messages = 1;
+}
+
+// Request for the ModifyAckDeadline method.
+message ModifyAckDeadlineRequest {
+ // Required. The name of the subscription.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+
+ // Required. List of acknowledgment IDs.
+ repeated string ack_ids = 4 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. The new ack deadline with respect to the time this request was
+ // sent to the Pub/Sub system. For example, if the value is 10, the new ack
+ // deadline will expire 10 seconds after the `ModifyAckDeadline` call was
+ // made. Specifying zero might immediately make the message available for
+ // delivery to another subscriber client. This typically results in an
+ // increase in the rate of message redeliveries (that is, duplicates).
+ // The minimum deadline you can specify is 0 seconds.
+ // The maximum deadline you can specify is 600 seconds (10 minutes).
+ int32 ack_deadline_seconds = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for the Acknowledge method.
+message AcknowledgeRequest {
+ // Required. The subscription whose message is being acknowledged.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+
+ // Required. The acknowledgment ID for the messages being acknowledged that
+ // was returned by the Pub/Sub system in the `Pull` response. Must not be
+ // empty.
+ repeated string ack_ids = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for the `StreamingPull` streaming RPC method. This request is used to
+// establish the initial stream as well as to stream acknowledgements and ack
+// deadline modifications from the client to the server.
+message StreamingPullRequest {
+ // Required. The subscription for which to initialize the new stream. This
+ // must be provided in the first request on the stream, and must not be set in
+ // subsequent requests from client to server.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+
+ // List of acknowledgement IDs for acknowledging previously received messages
+ // (received on this stream or a different stream). If an ack ID has expired,
+ // the corresponding message may be redelivered later. Acknowledging a message
+ // more than once will not result in an error. If the acknowledgement ID is
+ // malformed, the stream will be aborted with status `INVALID_ARGUMENT`.
+ repeated string ack_ids = 2;
+
+ // The list of new ack deadlines for the IDs listed in
+ // `modify_deadline_ack_ids`. The size of this list must be the same as the
+ // size of `modify_deadline_ack_ids`. If it differs the stream will be aborted
+ // with `INVALID_ARGUMENT`. Each element in this list is applied to the
+ // element in the same position in `modify_deadline_ack_ids`. The new ack
+ // deadline is with respect to the time this request was sent to the Pub/Sub
+ // system. Must be >= 0. For example, if the value is 10, the new ack deadline
+ // will expire 10 seconds after this request is received. If the value is 0,
+ // the message is immediately made available for another streaming or
+ // non-streaming pull request. If the value is < 0 (an error), the stream will
+ // be aborted with status `INVALID_ARGUMENT`.
+ repeated int32 modify_deadline_seconds = 3;
+
+ // List of acknowledgement IDs whose deadline will be modified based on the
+ // corresponding element in `modify_deadline_seconds`. This field can be used
+ // to indicate that more time is needed to process a message by the
+ // subscriber, or to make the message available for redelivery if the
+ // processing was interrupted.
+ repeated string modify_deadline_ack_ids = 4;
+
+ // Required. The ack deadline to use for the stream. This must be provided in
+ // the first request on the stream, but it can also be updated on subsequent
+ // requests from client to server. The minimum deadline you can specify is 10
+ // seconds. The maximum deadline you can specify is 600 seconds (10 minutes).
+ int32 stream_ack_deadline_seconds = 5
+ [(google.api.field_behavior) = REQUIRED];
+
+ // A unique identifier that is used to distinguish client instances from each
+ // other. Only needs to be provided on the initial request. When a stream
+ // disconnects and reconnects for the same stream, the client_id should be set
+ // to the same value so that state associated with the old stream can be
+ // transferred to the new stream. The same client_id should not be used for
+ // different client instances.
+ string client_id = 6;
+
+ // Flow control settings for the maximum number of outstanding messages. When
+ // there are `max_outstanding_messages` or more currently sent to the
+ // streaming pull client that have not yet been acked or nacked, the server
+ // stops sending more messages. The sending of messages resumes once the
+ // number of outstanding messages is less than this value. If the value is
+ // <= 0, there is no limit to the number of outstanding messages. This
+ // property can only be set on the initial StreamingPullRequest. If it is set
+ // on a subsequent request, the stream will be aborted with status
+ // `INVALID_ARGUMENT`.
+ int64 max_outstanding_messages = 7;
+
+ // Flow control settings for the maximum number of outstanding bytes. When
+ // there are `max_outstanding_bytes` or more worth of messages currently sent
+ // to the streaming pull client that have not yet been acked or nacked, the
+ // server will stop sending more messages. The sending of messages resumes
+ // once the number of outstanding bytes is less than this value. If the value
+ // is <= 0, there is no limit to the number of outstanding bytes. This
+ // property can only be set on the initial StreamingPullRequest. If it is set
+ // on a subsequent request, the stream will be aborted with status
+ // `INVALID_ARGUMENT`.
+ int64 max_outstanding_bytes = 8;
+}
+
+// Response for the `StreamingPull` method. This response is used to stream
+// messages from the server to the client.
+message StreamingPullResponse {
+ // Subscription properties sent as part of the response.
+ message SubscriptionProperties {
+ bool exactly_once_delivery_enabled = 1;
+ // True iff message ordering is enabled for this subscription.
+ bool message_ordering_enabled = 2;
+ }
+
+ // Received Pub/Sub messages. This will not be empty.
+ repeated ReceivedMessage received_messages = 1;
+
+ // Properties associated with this subscription.
+ SubscriptionProperties subscription_properties = 4;
+}
+
+// Request for the `CreateSnapshot` method.
+message CreateSnapshotRequest {
+ // Required. User-provided name for this snapshot. If the name is not provided
+ // in the request, the server will assign a random name for this snapshot on
+ // the same project as the subscription. Note that for REST API requests, you
+ // must specify a name. See the resource
+ // name rules . Format is `projects/{project}/snapshots/{snap}`.
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Snapshot" }
+ ];
+
+ // Required. The subscription whose backlog the snapshot retains.
+ // Specifically, the created snapshot is guaranteed to retain:
+ // (a) The existing backlog on the subscription. More precisely, this is
+ // defined as the messages in the subscription's backlog that are
+ // unacknowledged upon the successful completion of the
+ // `CreateSnapshot` request; as well as:
+ // (b) Any messages published to the subscription's topic following the
+ // successful completion of the CreateSnapshot request.
+ // Format is `projects/{project}/subscriptions/{sub}`.
+ string subscription = 2 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+
+ // See Creating and
+ // managing labels .
+ map labels = 3;
+}
+
+// Request for the UpdateSnapshot method.
+message UpdateSnapshotRequest {
+ // Required. The updated snapshot object.
+ Snapshot snapshot = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // Required. Indicates which fields in the provided snapshot to update.
+ // Must be specified and non-empty.
+ google.protobuf.FieldMask update_mask = 2
+ [(google.api.field_behavior) = REQUIRED];
+}
+
+// A snapshot resource. Snapshots are used in
+// [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+// operations, which allow you to manage message acknowledgments in bulk. That
+// is, you can set the acknowledgment state of messages in an existing
+// subscription to the state captured by a snapshot.
+message Snapshot {
+ option (google.api.resource) = {
+ type: "pubsub.googleapis.com/Snapshot"
+ pattern: "projects/{project}/snapshots/{snapshot}"
+ };
+
+ // The name of the snapshot.
+ string name = 1;
+
+ // The name of the topic from which this snapshot is retaining messages.
+ string topic = 2 [
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Topic" }
+ ];
+
+ // The snapshot is guaranteed to exist up until this time.
+ // A newly-created snapshot expires no later than 7 days from the time of its
+ // creation. Its exact lifetime is determined at creation by the existing
+ // backlog in the source subscription. Specifically, the lifetime of the
+ // snapshot is `7 days - (age of oldest unacked message in the subscription)`.
+ // For example, consider a subscription whose oldest unacked message is 3 days
+ // old. If a snapshot is created from this subscription, the snapshot -- which
+ // will always capture this 3-day-old backlog as long as the snapshot
+ // exists -- will expire in 4 days. The service will refuse to create a
+ // snapshot that would expire in less than 1 hour after creation.
+ google.protobuf.Timestamp expire_time = 3;
+
+ // See [Creating and managing labels]
+ // (https://cloud.google.com/pubsub/docs/labels).
+ map labels = 4;
+}
+
+// Request for the GetSnapshot method.
+message GetSnapshotRequest {
+ // Required. The name of the snapshot to get.
+ // Format is `projects/{project}/snapshots/{snap}`.
+ string snapshot = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Snapshot" }
+ ];
+}
+
+// Request for the `ListSnapshots` method.
+message ListSnapshotsRequest {
+ // Required. The name of the project in which to list snapshots.
+ // Format is `projects/{project-id}`.
+ string project = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "cloudresourcemanager.googleapis.com/Project"
+ }
+ ];
+
+ // Maximum number of snapshots to return.
+ int32 page_size = 2;
+
+ // The value returned by the last `ListSnapshotsResponse`; indicates that this
+ // is a continuation of a prior `ListSnapshots` call, and that the system
+ // should return the next page of data.
+ string page_token = 3;
+}
+
+// Response for the `ListSnapshots` method.
+message ListSnapshotsResponse {
+ // The resulting snapshots.
+ repeated Snapshot snapshots = 1;
+
+ // If not empty, indicates that there may be more snapshot that match the
+ // request; this value should be passed in a new `ListSnapshotsRequest`.
+ string next_page_token = 2;
+}
+
+// Request for the `DeleteSnapshot` method.
+message DeleteSnapshotRequest {
+ // Required. The name of the snapshot to delete.
+ // Format is `projects/{project}/snapshots/{snap}`.
+ string snapshot = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Snapshot" }
+ ];
+}
+
+// Request for the `Seek` method.
+message SeekRequest {
+ // Required. The subscription to affect.
+ string subscription = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Subscription"
+ }
+ ];
+
+ oneof target {
+ // The time to seek to.
+ // Messages retained in the subscription that were published before this
+ // time are marked as acknowledged, and messages retained in the
+ // subscription that were published after this time are marked as
+ // unacknowledged. Note that this operation affects only those messages
+ // retained in the subscription (configured by the combination of
+ // `message_retention_duration` and `retain_acked_messages`). For example,
+ // if `time` corresponds to a point before the message retention
+ // window (or to a point before the system's notion of the subscription
+ // creation time), only retained messages will be marked as unacknowledged,
+ // and already-expunged messages will not be restored.
+ google.protobuf.Timestamp time = 2;
+
+ // The snapshot to seek to. The snapshot's topic must be the same as that of
+ // the provided subscription.
+ // Format is `projects/{project}/snapshots/{snap}`.
+ string snapshot = 3 [(google.api.resource_reference) = {
+ type: "pubsub.googleapis.com/Snapshot"
+ }];
+ }
+}
+
+// Response for the `Seek` method (this response is empty).
+message SeekResponse {}
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/proto/schema.proto b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/proto/schema.proto
new file mode 100644
index 000000000000..1ace7ef3b0d7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/proto/schema.proto
@@ -0,0 +1,286 @@
+// Copyright 2020 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.pubsub.v1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/empty.proto";
+
+option cc_enable_arenas = true;
+option csharp_namespace = "Google.Cloud.PubSub.V1";
+option go_package = "google.golang.org/genproto/googleapis/pubsub/v1;pubsub";
+option java_multiple_files = true;
+option java_outer_classname = "SchemaProto";
+option java_package = "com.google.pubsub.v1";
+option php_namespace = "Google\\Cloud\\PubSub\\V1";
+option ruby_package = "Google::Cloud::PubSub::V1";
+
+// Service for doing schema-related operations.
+service SchemaService {
+ option (google.api.default_host) = "pubsub.googleapis.com";
+ option (google.api.oauth_scopes) =
+ "https://www.googleapis.com/auth/cloud-platform,"
+ "https://www.googleapis.com/auth/pubsub";
+
+ // Creates a schema.
+ rpc CreateSchema(CreateSchemaRequest) returns (Schema) {
+ option (google.api.http) = {
+ post: "/v1/{parent=projects/*}/schemas"
+ body: "schema"
+ };
+ option (google.api.method_signature) = "parent,schema,schema_id";
+ }
+
+ // Gets a schema.
+ rpc GetSchema(GetSchemaRequest) returns (Schema) {
+ option (google.api.http) = {
+ get: "/v1/{name=projects/*/schemas/*}"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Lists schemas in a project.
+ rpc ListSchemas(ListSchemasRequest) returns (ListSchemasResponse) {
+ option (google.api.http) = {
+ get: "/v1/{parent=projects/*}/schemas"
+ };
+ option (google.api.method_signature) = "parent";
+ }
+
+ // Deletes a schema.
+ rpc DeleteSchema(DeleteSchemaRequest) returns (google.protobuf.Empty) {
+ option (google.api.http) = {
+ delete: "/v1/{name=projects/*/schemas/*}"
+ };
+ option (google.api.method_signature) = "name";
+ }
+
+ // Validates a schema.
+ rpc ValidateSchema(ValidateSchemaRequest) returns (ValidateSchemaResponse) {
+ option (google.api.http) = {
+ post: "/v1/{parent=projects/*}/schemas:validate"
+ body: "*"
+ };
+ option (google.api.method_signature) = "parent,schema";
+ }
+
+ // Validates a message against a schema.
+ rpc ValidateMessage(ValidateMessageRequest)
+ returns (ValidateMessageResponse) {
+ option (google.api.http) = {
+ post: "/v1/{parent=projects/*}/schemas:validateMessage"
+ body: "*"
+ };
+ }
+}
+
+// A schema resource.
+message Schema {
+ option (google.api.resource) = {
+ type: "pubsub.googleapis.com/Schema"
+ pattern: "projects/{project}/schemas/{schema}"
+ };
+
+ // Possible schema definition types.
+ enum Type {
+ // Default value. This value is unused.
+ TYPE_UNSPECIFIED = 0;
+
+ // A Protocol Buffer schema definition.
+ PROTOCOL_BUFFER = 1;
+
+ // An Avro schema definition.
+ AVRO = 2;
+ }
+
+ // Required. Name of the schema.
+ // Format is `projects/{project}/schemas/{schema}`.
+ string name = 1 [(google.api.field_behavior) = REQUIRED];
+
+ // The type of the schema definition.
+ Type type = 2;
+
+ // The definition of the schema. This should contain a string representing
+ // the full definition of the schema that is a valid schema definition of
+ // the type specified in `type`.
+ string definition = 3;
+}
+
+// Request for the CreateSchema method.
+message CreateSchemaRequest {
+ // Required. The name of the project in which to create the schema.
+ // Format is `projects/{project-id}`.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ child_type: "pubsub.googleapis.com/Schema"
+ }
+ ];
+
+ // Required. The schema object to create.
+ //
+ // This schema's `name` parameter is ignored. The schema object returned
+ // by CreateSchema will have a `name` made using the given `parent` and
+ // `schema_id`.
+ Schema schema = 2 [(google.api.field_behavior) = REQUIRED];
+
+ // The ID to use for the schema, which will become the final component of
+ // the schema's resource name.
+ //
+ // See https://cloud.google.com/pubsub/docs/admin#resource_names for resource
+ // name constraints.
+ string schema_id = 3;
+}
+
+// View of Schema object fields to be returned by GetSchema and ListSchemas.
+enum SchemaView {
+ // The default / unset value.
+ // The API will default to the BASIC view.
+ SCHEMA_VIEW_UNSPECIFIED = 0;
+
+ // Include the name and type of the schema, but not the definition.
+ BASIC = 1;
+
+ // Include all Schema object fields.
+ FULL = 2;
+}
+
+// Request for the GetSchema method.
+message GetSchemaRequest {
+ // Required. The name of the schema to get.
+ // Format is `projects/{project}/schemas/{schema}`.
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+ ];
+
+ // The set of fields to return in the response. If not set, returns a Schema
+ // with `name` and `type`, but not `definition`. Set to `FULL` to retrieve all
+ // fields.
+ SchemaView view = 2;
+}
+
+// Request for the `ListSchemas` method.
+message ListSchemasRequest {
+ // Required. The name of the project in which to list schemas.
+ // Format is `projects/{project-id}`.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "cloudresourcemanager.googleapis.com/Project"
+ }
+ ];
+
+ // The set of Schema fields to return in the response. If not set, returns
+ // Schemas with `name` and `type`, but not `definition`. Set to `FULL` to
+ // retrieve all fields.
+ SchemaView view = 2;
+
+ // Maximum number of schemas to return.
+ int32 page_size = 3;
+
+ // The value returned by the last `ListSchemasResponse`; indicates that
+ // this is a continuation of a prior `ListSchemas` call, and that the
+ // system should return the next page of data.
+ string page_token = 4;
+}
+
+// Response for the `ListSchemas` method.
+message ListSchemasResponse {
+ // The resulting schemas.
+ repeated Schema schemas = 1;
+
+ // If not empty, indicates that there may be more schemas that match the
+ // request; this value should be passed in a new `ListSchemasRequest`.
+ string next_page_token = 2;
+}
+
+// Request for the `DeleteSchema` method.
+message DeleteSchemaRequest {
+ // Required. Name of the schema to delete.
+ // Format is `projects/{project}/schemas/{schema}`.
+ string name = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+ ];
+}
+
+// Request for the `ValidateSchema` method.
+message ValidateSchemaRequest {
+ // Required. The name of the project in which to validate schemas.
+ // Format is `projects/{project-id}`.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "cloudresourcemanager.googleapis.com/Project"
+ }
+ ];
+
+ // Required. The schema object to validate.
+ Schema schema = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Response for the `ValidateSchema` method.
+message ValidateSchemaResponse {}
+
+// Request for the `ValidateMessage` method.
+message ValidateMessageRequest {
+ // Required. The name of the project in which to validate schemas.
+ // Format is `projects/{project-id}`.
+ string parent = 1 [
+ (google.api.field_behavior) = REQUIRED,
+ (google.api.resource_reference) = {
+ type: "cloudresourcemanager.googleapis.com/Project"
+ }
+ ];
+
+ oneof schema_spec {
+ // Name of the schema against which to validate.
+ //
+ // Format is `projects/{project}/schemas/{schema}`.
+ string name = 2 [
+ (google.api.resource_reference) = { type: "pubsub.googleapis.com/Schema" }
+ ];
+
+ // Ad-hoc schema against which to validate
+ Schema schema = 3;
+ }
+
+ // Message to validate against the provided `schema_spec`.
+ bytes message = 4;
+
+ // The encoding expected for messages
+ Encoding encoding = 5;
+}
+
+// Response for the `ValidateMessage` method.
+message ValidateMessageResponse {}
+
+// Possible encoding types for messages.
+enum Encoding {
+ // Unspecified
+ ENCODING_UNSPECIFIED = 0;
+
+ // JSON encoding
+ JSON = 1;
+
+ // Binary encoding, as defined by the schema type. For some schema types,
+ // binary encoding may not be available.
+ BINARY = 2;
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/__init__.py
new file mode 100644
index 000000000000..688ee744b7b4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/__init__.py
@@ -0,0 +1,20 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+from google.cloud.pubsub_v1.publisher.client import Client
+
+
+__all__ = ("Client",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/base.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/base.py
new file mode 100644
index 000000000000..52505996be0b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/base.py
@@ -0,0 +1,170 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import abc
+import enum
+import typing
+from typing import Optional, Sequence
+
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud import pubsub_v1
+ from google.cloud.pubsub_v1 import types
+ from google.pubsub_v1 import types as gapic_types
+
+
+class Batch(metaclass=abc.ABCMeta):
+ """The base batching class for Pub/Sub publishing.
+
+ Although the :class:`~.pubsub_v1.publisher.batch.thread.Batch` class, based
+ on :class:`threading.Thread`, is fine for most cases, advanced
+ users may need to implement something based on a different concurrency
+ model.
+
+ This class defines the interface for the Batch implementation;
+ subclasses may be passed as the ``batch_class`` argument to
+ :class:`~.pubsub_v1.client.PublisherClient`.
+
+ The batching behavior works like this: When the
+ :class:`~.pubsub_v1.publisher.client.Client` is asked to publish a new
+ message, it requires a batch. The client will see if there is an
+ already-opened batch for the given topic; if there is, then the message
+ is sent to that batch. If there is not, then a new batch is created
+ and the message put there.
+
+ When a new batch is created, it automatically starts a timer counting
+ down to the maximum latency before the batch should commit.
+ Essentially, if enough time passes, the batch automatically commits
+ regardless of how much is in it. However, if either the message count or
+ size thresholds are encountered first, then the batch will commit early.
+ """
+
+ def __len__(self):
+ """Return the number of messages currently in the batch."""
+ return len(self.messages)
+
+ @staticmethod
+ @abc.abstractmethod
+ def make_lock(): # pragma: NO COVER
+ """Return a lock in the chosen concurrency model.
+
+ Returns:
+ ContextManager: A newly created lock.
+ """
+ raise NotImplementedError
+
+ @property
+ @abc.abstractmethod
+ def messages(self) -> Sequence["gapic_types.PubsubMessage"]: # pragma: NO COVER
+ """Return the messages currently in the batch.
+
+ Returns:
+ The messages currently in the batch.
+ """
+ raise NotImplementedError
+
+ @property
+ @abc.abstractmethod
+ def size(self) -> int: # pragma: NO COVER
+ """Return the total size of all of the messages currently in the batch.
+
+ The size includes any overhead of the actual ``PublishRequest`` that is
+ sent to the backend.
+
+ Returns:
+ int: The total size of all of the messages currently
+ in the batch (including the request overhead), in bytes.
+ """
+ raise NotImplementedError
+
+ @property
+ @abc.abstractmethod
+ def settings(self) -> "types.BatchSettings": # pragma: NO COVER
+ """Return the batch settings.
+
+ Returns:
+ The batch settings. These are considered immutable once the batch has
+ been opened.
+ """
+ raise NotImplementedError
+
+ @property
+ @abc.abstractmethod
+ def status(self) -> "BatchStatus": # pragma: NO COVER
+ """Return the status of this batch.
+
+ Returns:
+ The status of this batch. All statuses are human-readable, all-lowercase
+ strings. The ones represented in the :class:`BaseBatch.Status` enum are
+ special, but other statuses are permitted.
+ """
+ raise NotImplementedError
+
+ def cancel(
+ self, cancellation_reason: "BatchCancellationReason"
+ ) -> None: # pragma: NO COVER
+ """Complete pending futures with an exception.
+
+ This method must be called before publishing starts (ie: while the
+ batch is still accepting messages.)
+
+ Args:
+ cancellation_reason:
+ The reason why this batch has been cancelled.
+ """
+ raise NotImplementedError
+
+ @abc.abstractmethod
+ def publish(
+ self, message: "gapic_types.PubsubMessage"
+ ) -> Optional["pubsub_v1.publisher.futures.Future"]: # pragma: NO COVER
+ """Publish a single message.
+
+ Add the given message to this object; this will cause it to be
+ published once the batch either has enough messages or a sufficient
+ period of time has elapsed.
+
+ This method is called by :meth:`~.PublisherClient.publish`.
+
+ Args:
+ message: The Pub/Sub message.
+
+ Returns:
+ An object conforming to the :class:`concurrent.futures.Future` interface.
+ If :data:`None` is returned, that signals that the batch cannot
+ accept a message.
+ """
+ raise NotImplementedError
+
+
+class BatchStatus(str, enum.Enum):
+ """An enum-like class representing valid statuses for a batch."""
+
+ ACCEPTING_MESSAGES = "accepting messages"
+ STARTING = "starting"
+ IN_PROGRESS = "in progress"
+ ERROR = "error"
+ SUCCESS = "success"
+
+
+class BatchCancellationReason(str, enum.Enum):
+ """An enum-like class representing reasons why a batch was cancelled."""
+
+ PRIOR_ORDERED_MESSAGE_FAILED = (
+ "Batch cancelled because prior ordered message for the same key has "
+ "failed. This batch has been cancelled to avoid out-of-order publish."
+ )
+ CLIENT_STOPPED = "Batch cancelled because the publisher client has been stopped."
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/thread.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/thread.py
new file mode 100644
index 000000000000..8b868eaee88f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_batch/thread.py
@@ -0,0 +1,409 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import logging
+import threading
+import time
+import typing
+from typing import Any, Callable, List, Optional, Sequence
+
+import google.api_core.exceptions
+from google.api_core import gapic_v1
+from google.cloud.pubsub_v1.publisher import exceptions
+from google.cloud.pubsub_v1.publisher import futures
+from google.cloud.pubsub_v1.publisher._batch import base
+from google.pubsub_v1 import types as gapic_types
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud import pubsub_v1
+ from google.cloud.pubsub_v1 import types
+ from google.cloud.pubsub_v1.publisher import Client as PublisherClient
+ from google.pubsub_v1.services.publisher.client import OptionalRetry
+
+_LOGGER = logging.getLogger(__name__)
+_CAN_COMMIT = (base.BatchStatus.ACCEPTING_MESSAGES, base.BatchStatus.STARTING)
+_SERVER_PUBLISH_MAX_BYTES = 10 * 1000 * 1000 # max accepted size of PublishRequest
+
+_raw_proto_pubbsub_message = gapic_types.PubsubMessage.pb()
+
+
+class Batch(base.Batch):
+ """A batch of messages.
+
+ The batch is the internal group of messages which are either awaiting
+ publication or currently in progress.
+
+ A batch is automatically created by the PublisherClient when the first
+ message to be published is received; subsequent messages are added to
+ that batch until the process of actual publishing _starts_.
+
+ Once this occurs, any new messages sent to :meth:`publish` open a new
+ batch.
+
+ If you are using this library, you most likely do not need to instantiate
+ batch objects directly; they will be created for you. If you want to
+ change the actual batching settings, see the ``batching`` argument on
+ :class:`~.pubsub_v1.PublisherClient`.
+
+ Any properties or methods on this class which are not defined in
+ :class:`~.pubsub_v1.publisher.batch.BaseBatch` should be considered
+ implementation details.
+
+ Args:
+ client:
+ The publisher client used to create this batch.
+ topic:
+ The topic. The format for this is ``projects/{project}/topics/{topic}``.
+ settings:
+ The settings for batch publishing. These should be considered immutable
+ once the batch has been opened.
+ batch_done_callback:
+ Callback called when the response for a batch publish has been received.
+ Called with one boolean argument: successfully published or a permanent
+ error occurred. Temporary errors are not surfaced because they are retried
+ at a lower level.
+ commit_when_full:
+ Whether to commit the batch when the batch is full.
+ commit_retry:
+ Designation of what errors, if any, should be retried when commiting
+ the batch. If not provided, a default retry is used.
+ commit_timeout:
+ The timeout to apply when commiting the batch. If not provided, a default
+ timeout is used.
+ """
+
+ def __init__(
+ self,
+ client: "PublisherClient",
+ topic: str,
+ settings: "types.BatchSettings",
+ batch_done_callback: Callable[[bool], Any] = None,
+ commit_when_full: bool = True,
+ commit_retry: "OptionalRetry" = gapic_v1.method.DEFAULT,
+ commit_timeout: "types.OptionalTimeout" = gapic_v1.method.DEFAULT,
+ ):
+ self._client = client
+ self._topic = topic
+ self._settings = settings
+ self._batch_done_callback = batch_done_callback
+ self._commit_when_full = commit_when_full
+
+ self._state_lock = threading.Lock()
+ # These members are all communicated between threads; ensure that
+ # any writes to them use the "state lock" to remain atomic.
+ # _futures list should remain unchanged after batch
+ # status changed from ACCEPTING_MESSAGES to any other
+ # in order to avoid race conditions
+ self._futures: List[futures.Future] = []
+ self._messages: List[gapic_types.PubsubMessage] = []
+ self._status = base.BatchStatus.ACCEPTING_MESSAGES
+
+ # The initial size is not zero, we need to account for the size overhead
+ # of the PublishRequest message itself.
+ self._base_request_size = gapic_types.PublishRequest(topic=topic)._pb.ByteSize()
+ self._size = self._base_request_size
+
+ self._commit_retry = commit_retry
+ self._commit_timeout = commit_timeout
+
+ @staticmethod
+ def make_lock() -> threading.Lock:
+ """Return a threading lock.
+
+ Returns:
+ A newly created lock.
+ """
+ return threading.Lock()
+
+ @property
+ def client(self) -> "PublisherClient":
+ """A publisher client."""
+ return self._client
+
+ @property
+ def messages(self) -> Sequence[gapic_types.PubsubMessage]:
+ """The messages currently in the batch."""
+ return self._messages
+
+ @property
+ def settings(self) -> "types.BatchSettings":
+ """Return the batch settings.
+
+ Returns:
+ The batch settings. These are considered immutable once the batch has
+ been opened.
+ """
+ return self._settings
+
+ @property
+ def size(self) -> int:
+ """Return the total size of all of the messages currently in the batch.
+
+ The size includes any overhead of the actual ``PublishRequest`` that is
+ sent to the backend.
+
+ Returns:
+ The total size of all of the messages currently in the batch (including
+ the request overhead), in bytes.
+ """
+ return self._size
+
+ @property
+ def status(self) -> base.BatchStatus:
+ """Return the status of this batch.
+
+ Returns:
+ The status of this batch. All statuses are human-readable, all-lowercase
+ strings.
+ """
+ return self._status
+
+ def cancel(self, cancellation_reason: base.BatchCancellationReason) -> None:
+ """Complete pending futures with an exception.
+
+ This method must be called before publishing starts (ie: while the
+ batch is still accepting messages.)
+
+ Args:
+ The reason why this batch has been cancelled.
+ """
+
+ with self._state_lock:
+ assert (
+ self._status == base.BatchStatus.ACCEPTING_MESSAGES
+ ), "Cancel should not be called after sending has started."
+
+ exc = RuntimeError(cancellation_reason.value)
+ for future in self._futures:
+ future.set_exception(exc)
+ self._status = base.BatchStatus.ERROR
+
+ def commit(self) -> None:
+ """Actually publish all of the messages on the active batch.
+
+ .. note::
+
+ This method is non-blocking. It opens a new thread, which calls
+ :meth:`_commit`, which does block.
+
+ This synchronously sets the batch status to "starting", and then opens
+ a new thread, which handles actually sending the messages to Pub/Sub.
+
+ If the current batch is **not** accepting messages, this method
+ does nothing.
+ """
+
+ # Set the status to "starting" synchronously, to ensure that
+ # this batch will necessarily not accept new messages.
+ with self._state_lock:
+ if self._status == base.BatchStatus.ACCEPTING_MESSAGES:
+ self._status = base.BatchStatus.STARTING
+ else:
+ return
+
+ self._start_commit_thread()
+
+ def _start_commit_thread(self) -> None:
+ """Start a new thread to actually handle the commit."""
+ # NOTE: If the thread is *not* a daemon, a memory leak exists due to a CPython issue.
+ # https://github.com/googleapis/python-pubsub/issues/395#issuecomment-829910303
+ # https://github.com/googleapis/python-pubsub/issues/395#issuecomment-830092418
+ commit_thread = threading.Thread(
+ name="Thread-CommitBatchPublisher", target=self._commit, daemon=True
+ )
+ commit_thread.start()
+
+ def _commit(self) -> None:
+ """Actually publish all of the messages on the active batch.
+
+ This moves the batch out from being the active batch to an in progress
+ batch on the publisher, and then the batch is discarded upon
+ completion.
+
+ .. note::
+
+ This method blocks. The :meth:`commit` method is the non-blocking
+ version, which calls this one.
+ """
+ with self._state_lock:
+ if self._status in _CAN_COMMIT:
+ self._status = base.BatchStatus.IN_PROGRESS
+ else:
+ # If, in the intervening period between when this method was
+ # called and now, the batch started to be committed, or
+ # completed a commit, then no-op at this point.
+ _LOGGER.debug(
+ "Batch is already in progress or has been cancelled, "
+ "exiting commit"
+ )
+ return
+
+ # Once in the IN_PROGRESS state, no other thread can publish additional
+ # messages or initiate a commit (those operations become a no-op), thus
+ # it is safe to release the state lock here. Releasing the lock avoids
+ # blocking other threads in case api.publish() below takes a long time
+ # to complete.
+ # https://github.com/googleapis/google-cloud-python/issues/8036
+
+ # Sanity check: If there are no messages, no-op.
+ if not self._messages:
+ _LOGGER.debug("No messages to publish, exiting commit")
+ self._status = base.BatchStatus.SUCCESS
+ return
+
+ # Begin the request to publish these messages.
+ # Log how long the underlying request takes.
+ start = time.time()
+
+ batch_transport_succeeded = True
+ try:
+ # Performs retries for errors defined by the retry configuration.
+ response = self._client._gapic_publish(
+ topic=self._topic,
+ messages=self._messages,
+ retry=self._commit_retry,
+ timeout=self._commit_timeout,
+ )
+ except google.api_core.exceptions.GoogleAPIError as exc:
+ # We failed to publish, even after retries, so set the exception on
+ # all futures and exit.
+ self._status = base.BatchStatus.ERROR
+
+ for future in self._futures:
+ future.set_exception(exc)
+
+ batch_transport_succeeded = False
+ if self._batch_done_callback is not None:
+ # Failed to publish batch.
+ self._batch_done_callback(batch_transport_succeeded)
+
+ _LOGGER.exception("Failed to publish %s messages.", len(self._futures))
+ return
+
+ end = time.time()
+ _LOGGER.debug("gRPC Publish took %s seconds.", end - start)
+
+ if len(response.message_ids) == len(self._futures):
+ # Iterate over the futures on the queue and return the response
+ # IDs. We are trusting that there is a 1:1 mapping, and raise
+ # an exception if not.
+ self._status = base.BatchStatus.SUCCESS
+ for message_id, future in zip(response.message_ids, self._futures):
+ future.set_result(message_id)
+ else:
+ # Sanity check: If the number of message IDs is not equal to
+ # the number of futures I have, then something went wrong.
+ self._status = base.BatchStatus.ERROR
+ exception = exceptions.PublishError(
+ "Some messages were not successfully published."
+ )
+
+ for future in self._futures:
+ future.set_exception(exception)
+
+ # Unknown error -> batch failed to be correctly transported/
+ batch_transport_succeeded = False
+
+ _LOGGER.error(
+ "Only %s of %s messages were published.",
+ len(response.message_ids),
+ len(self._futures),
+ )
+
+ if self._batch_done_callback is not None:
+ self._batch_done_callback(batch_transport_succeeded)
+
+ def publish(
+ self, message: gapic_types.PubsubMessage
+ ) -> Optional["pubsub_v1.publisher.futures.Future"]:
+ """Publish a single message.
+
+ Add the given message to this object; this will cause it to be
+ published once the batch either has enough messages or a sufficient
+ period of time has elapsed. If the batch is full or the commit is
+ already in progress, the method does not do anything.
+
+ This method is called by :meth:`~.PublisherClient.publish`.
+
+ Args:
+ message: The Pub/Sub message.
+
+ Returns:
+ An object conforming to the :class:`~concurrent.futures.Future` interface
+ or :data:`None`. If :data:`None` is returned, that signals that the batch
+ cannot accept a message.
+
+ Raises:
+ pubsub_v1.publisher.exceptions.MessageTooLargeError: If publishing
+ the ``message`` would exceed the max size limit on the backend.
+ """
+
+ # Coerce the type, just in case.
+ if not isinstance(message, gapic_types.PubsubMessage):
+ # For performance reasons, the message should be constructed by directly
+ # using the raw protobuf class, and only then wrapping it into the
+ # higher-level PubsubMessage class.
+ vanilla_pb = _raw_proto_pubbsub_message(**message)
+ message = gapic_types.PubsubMessage.wrap(vanilla_pb)
+
+ future = None
+
+ with self._state_lock:
+ assert (
+ self._status != base.BatchStatus.ERROR
+ ), "Publish after stop() or publish error."
+
+ if self.status != base.BatchStatus.ACCEPTING_MESSAGES:
+ return None
+
+ size_increase = gapic_types.PublishRequest(
+ messages=[message]
+ )._pb.ByteSize()
+
+ if (self._base_request_size + size_increase) > _SERVER_PUBLISH_MAX_BYTES:
+ err_msg = (
+ "The message being published would produce too large a publish "
+ "request that would exceed the maximum allowed size on the "
+ "backend ({} bytes).".format(_SERVER_PUBLISH_MAX_BYTES)
+ )
+ raise exceptions.MessageTooLargeError(err_msg)
+
+ new_size = self._size + size_increase
+ new_count = len(self._messages) + 1
+
+ size_limit = min(self.settings.max_bytes, _SERVER_PUBLISH_MAX_BYTES)
+ overflow = new_size > size_limit or new_count >= self.settings.max_messages
+
+ if not self._messages or not overflow:
+
+ # Store the actual message in the batch's message queue.
+ self._messages.append(message)
+ self._size = new_size
+
+ # Track the future on this batch (so that the result of the
+ # future can be set).
+ future = futures.Future()
+ self._futures.append(future)
+
+ # Try to commit, but it must be **without** the lock held, since
+ # ``commit()`` will try to obtain the lock.
+ if self._commit_when_full and overflow:
+ self.commit()
+
+ return future
+
+ def _set_status(self, status: base.BatchStatus):
+ self._status = status
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/base.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/base.py
new file mode 100644
index 000000000000..58ec5a571bb8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/base.py
@@ -0,0 +1,82 @@
+# Copyright 2019, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import abc
+import typing
+
+from google.api_core import gapic_v1
+from google.pubsub_v1 import types as gapic_types
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from concurrent import futures
+ from google.pubsub_v1.services.publisher.client import OptionalRetry
+
+
+class Sequencer(metaclass=abc.ABCMeta):
+ """The base class for sequencers for Pub/Sub publishing. A sequencer
+ sequences messages to be published.
+ """
+
+ @abc.abstractmethod
+ def is_finished(self) -> bool: # pragma: NO COVER
+ """Whether the sequencer is finished and should be cleaned up.
+
+ Returns:
+ bool: Whether the sequencer is finished and should be cleaned up.
+ """
+ raise NotImplementedError
+
+ @abc.abstractmethod
+ def unpause(self) -> None: # pragma: NO COVER
+ """Unpauses this sequencer.
+
+ Raises:
+ RuntimeError:
+ If called when the sequencer has not been paused.
+ """
+ raise NotImplementedError
+
+ @abc.abstractmethod
+ def publish(
+ self,
+ message: gapic_types.PubsubMessage,
+ retry: "OptionalRetry" = gapic_v1.method.DEFAULT,
+ timeout: gapic_types.TimeoutType = gapic_v1.method.DEFAULT,
+ ) -> "futures.Future": # pragma: NO COVER
+ """Publish message for this ordering key.
+
+ Args:
+ message:
+ The Pub/Sub message.
+ retry:
+ The retry settings to apply when publishing the message.
+ timeout:
+ The timeout to apply when publishing the message.
+
+ Returns:
+ A class instance that conforms to Python Standard library's
+ :class:`~concurrent.futures.Future` interface. The future might return
+ immediately with a
+ `pubsub_v1.publisher.exceptions.PublishToPausedOrderingKeyException`
+ if the ordering key is paused. Otherwise, the future tracks the
+ lifetime of the message publish.
+
+ Raises:
+ RuntimeError:
+ If called after this sequencer has been stopped, either by
+ a call to stop() or after all batches have been published.
+ """
+ raise NotImplementedError
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/ordered_sequencer.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/ordered_sequencer.py
new file mode 100644
index 000000000000..30c76a44f4d2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/ordered_sequencer.py
@@ -0,0 +1,338 @@
+# Copyright 2019, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import enum
+import collections
+import threading
+import typing
+from typing import Deque, Iterable, Sequence
+
+from google.api_core import gapic_v1
+from google.cloud.pubsub_v1.publisher import futures
+from google.cloud.pubsub_v1.publisher import exceptions
+from google.cloud.pubsub_v1.publisher._sequencer import base as sequencer_base
+from google.cloud.pubsub_v1.publisher._batch import base as batch_base
+from google.pubsub_v1 import types as gapic_types
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1 import types
+ from google.cloud.pubsub_v1.publisher import _batch
+ from google.cloud.pubsub_v1.publisher.client import Client as PublisherClient
+ from google.pubsub_v1.services.publisher.client import OptionalRetry
+
+
+class _OrderedSequencerStatus(str, enum.Enum):
+ """An enum-like class representing valid statuses for an OrderedSequencer.
+
+ Starting state: ACCEPTING_MESSAGES
+ Valid transitions:
+ ACCEPTING_MESSAGES -> PAUSED (on permanent error)
+ ACCEPTING_MESSAGES -> STOPPED (when user calls stop() explicitly)
+ ACCEPTING_MESSAGES -> FINISHED (all batch publishes finish normally)
+
+ PAUSED -> ACCEPTING_MESSAGES (when user unpauses)
+ PAUSED -> STOPPED (when user calls stop() explicitly)
+
+ STOPPED -> FINISHED (user stops client and the one remaining batch finishes
+ publish)
+ STOPPED -> PAUSED (stop() commits one batch, which fails permanently)
+
+ FINISHED -> ACCEPTING_MESSAGES (publish happens while waiting for cleanup)
+ FINISHED -> STOPPED (when user calls stop() explicitly)
+ Illegal transitions:
+ PAUSED -> FINISHED (since all batches are cancelled on pause, there should
+ not be any that finish normally. paused sequencers
+ should not be cleaned up because their presence
+ indicates that the ordering key needs to be resumed)
+ STOPPED -> ACCEPTING_MESSAGES (no way to make a user-stopped sequencer
+ accept messages again. this is okay since
+ stop() should only be called on shutdown.)
+ FINISHED -> PAUSED (no messages remain in flight, so they can't cause a
+ permanent error and pause the sequencer)
+ """
+
+ # Accepting publishes and/or waiting for result of batch publish
+ ACCEPTING_MESSAGES = "accepting messages"
+ # Permanent error occurred. User must unpause this sequencer to resume
+ # publishing. This is done to maintain ordering.
+ PAUSED = "paused"
+ # No more publishes allowed. There may be an outstanding batch that will
+ # call the _batch_done_callback when it's done (success or error.)
+ STOPPED = "stopped"
+ # No more work to do. Waiting to be cleaned-up. A publish will transform
+ # this sequencer back into the normal accepting-messages state.
+ FINISHED = "finished"
+
+
+class OrderedSequencer(sequencer_base.Sequencer):
+ """Sequences messages into batches ordered by an ordering key for one topic.
+
+ A sequencer always has at least one batch in it, unless paused or stopped.
+ When no batches remain, the |publishes_done_callback| is called so the
+ client can perform cleanup.
+
+ Public methods are thread-safe.
+
+ Args:
+ client:
+ The publisher client used to create this sequencer.
+ topic:
+ The topic. The format for this is ``projects/{project}/topics/{topic}``.
+ ordering_key:
+ The ordering key for this sequencer.
+ """
+
+ def __init__(self, client: "PublisherClient", topic: str, ordering_key: str):
+ self._client = client
+ self._topic = topic
+ self._ordering_key = ordering_key
+ # Guards the variables below
+ self._state_lock = threading.Lock()
+ # Batches ordered from first (head/left) to last (right/tail).
+ # Invariant: always has at least one batch after the first publish,
+ # unless paused or stopped.
+ self._ordered_batches: Deque["_batch.thread.Batch"] = collections.deque()
+ # See _OrderedSequencerStatus for valid state transitions.
+ self._state = _OrderedSequencerStatus.ACCEPTING_MESSAGES
+
+ def is_finished(self) -> bool:
+ """Whether the sequencer is finished and should be cleaned up.
+
+ Returns:
+ Whether the sequencer is finished and should be cleaned up.
+ """
+ with self._state_lock:
+ return self._state == _OrderedSequencerStatus.FINISHED
+
+ def stop(self) -> None:
+ """Permanently stop this sequencer.
+
+ This differs from pausing, which may be resumed. Immediately commits
+ the first batch and cancels the rest.
+
+ Raises:
+ RuntimeError:
+ If called after stop() has already been called.
+ """
+ with self._state_lock:
+ if self._state == _OrderedSequencerStatus.STOPPED:
+ raise RuntimeError("Ordered sequencer already stopped.")
+
+ self._state = _OrderedSequencerStatus.STOPPED
+ if self._ordered_batches:
+ # Give only the first batch the chance to finish.
+ self._ordered_batches[0].commit()
+
+ # Cancel the rest of the batches and remove them from the deque
+ # of batches.
+ while len(self._ordered_batches) > 1:
+ # Pops from the tail until it leaves only the head in the
+ # deque.
+ batch = self._ordered_batches.pop()
+ batch.cancel(batch_base.BatchCancellationReason.CLIENT_STOPPED)
+
+ def commit(self) -> None:
+ """Commit the first batch, if unpaused.
+
+ If paused or no batches exist, this method does nothing.
+
+ Raises:
+ RuntimeError:
+ If called after stop() has already been called.
+ """
+ with self._state_lock:
+ if self._state == _OrderedSequencerStatus.STOPPED:
+ raise RuntimeError("Ordered sequencer already stopped.")
+
+ if self._state != _OrderedSequencerStatus.PAUSED and self._ordered_batches:
+ # It's okay to commit the same batch more than once. The
+ # operation is idempotent.
+ self._ordered_batches[0].commit()
+
+ def _batch_done_callback(self, success: bool) -> None:
+ """Deal with completion of a batch.
+
+ Called when a batch has finished publishing, with either a success
+ or a failure. (Temporary failures are retried infinitely when
+ ordering keys are enabled.)
+ """
+ ensure_cleanup_and_commit_timer_runs = False
+ with self._state_lock:
+ assert self._state != _OrderedSequencerStatus.PAUSED, (
+ "This method should not be called after pause() because "
+ "pause() should have cancelled all of the batches."
+ )
+ assert self._state != _OrderedSequencerStatus.FINISHED, (
+ "This method should not be called after all batches have been "
+ "finished."
+ )
+
+ # Message futures for the batch have been completed (either with a
+ # result or an exception) already, so remove the batch.
+ self._ordered_batches.popleft()
+
+ if success:
+ if len(self._ordered_batches) == 0:
+ # Mark this sequencer as finished.
+ # If new messages come in for this ordering key and this
+ # sequencer hasn't been cleaned up yet, it will go back
+ # into accepting-messages state. Otherwise, the client
+ # must create a new OrderedSequencer.
+ self._state = _OrderedSequencerStatus.FINISHED
+ # Ensure cleanup thread runs at some point.
+ ensure_cleanup_and_commit_timer_runs = True
+ elif len(self._ordered_batches) == 1:
+ # Wait for messages and/or commit timeout
+ # Ensure there's actually a commit timer thread that'll commit
+ # after a delay.
+ ensure_cleanup_and_commit_timer_runs = True
+ else:
+ # If there is more than one batch, we know that the next batch
+ # must be full and, therefore, ready to be committed.
+ self._ordered_batches[0].commit()
+ else:
+ # Unrecoverable error detected
+ self._pause()
+
+ if ensure_cleanup_and_commit_timer_runs:
+ self._client.ensure_cleanup_and_commit_timer_runs()
+
+ def _pause(self) -> None:
+ """Pause this sequencer: set state to paused, cancel all batches, and
+ clear the list of ordered batches.
+
+ _state_lock must be taken before calling this method.
+ """
+ assert (
+ self._state != _OrderedSequencerStatus.FINISHED
+ ), "Pause should not be called after all batches have finished."
+ self._state = _OrderedSequencerStatus.PAUSED
+ for batch in self._ordered_batches:
+ batch.cancel(
+ batch_base.BatchCancellationReason.PRIOR_ORDERED_MESSAGE_FAILED
+ )
+ self._ordered_batches.clear()
+
+ def unpause(self) -> None:
+ """Unpause this sequencer.
+
+ Raises:
+ RuntimeError:
+ If called when the ordering key has not been paused.
+ """
+ with self._state_lock:
+ if self._state != _OrderedSequencerStatus.PAUSED:
+ raise RuntimeError("Ordering key is not paused.")
+ self._state = _OrderedSequencerStatus.ACCEPTING_MESSAGES
+
+ def _create_batch(
+ self,
+ commit_retry: "OptionalRetry" = gapic_v1.method.DEFAULT,
+ commit_timeout: "types.OptionalTimeout" = gapic_v1.method.DEFAULT,
+ ) -> "_batch.thread.Batch":
+ """Create a new batch using the client's batch class and other stored
+ settings.
+
+ Args:
+ commit_retry:
+ The retry settings to apply when publishing the batch.
+ commit_timeout:
+ The timeout to apply when publishing the batch.
+ """
+ return self._client._batch_class(
+ client=self._client,
+ topic=self._topic,
+ settings=self._client.batch_settings,
+ batch_done_callback=self._batch_done_callback,
+ commit_when_full=False,
+ commit_retry=commit_retry,
+ commit_timeout=commit_timeout,
+ )
+
+ def publish(
+ self,
+ message: gapic_types.PubsubMessage,
+ retry: "OptionalRetry" = gapic_v1.method.DEFAULT,
+ timeout: "types.OptionalTimeout" = gapic_v1.method.DEFAULT,
+ ) -> futures.Future:
+ """Publish message for this ordering key.
+
+ Args:
+ message:
+ The Pub/Sub message.
+ retry:
+ The retry settings to apply when publishing the message.
+ timeout:
+ The timeout to apply when publishing the message.
+
+ Returns:
+ A class instance that conforms to Python Standard library's
+ :class:`~concurrent.futures.Future` interface (but not an
+ instance of that class). The future might return immediately with a
+ PublishToPausedOrderingKeyException if the ordering key is paused.
+ Otherwise, the future tracks the lifetime of the message publish.
+
+ Raises:
+ RuntimeError:
+ If called after this sequencer has been stopped, either by
+ a call to stop() or after all batches have been published.
+ """
+ with self._state_lock:
+ if self._state == _OrderedSequencerStatus.PAUSED:
+ errored_future = futures.Future()
+ exception = exceptions.PublishToPausedOrderingKeyException(
+ self._ordering_key
+ )
+ errored_future.set_exception(exception)
+ return errored_future
+
+ # If waiting to be cleaned-up, convert to accepting messages to
+ # prevent this sequencer from being cleaned-up only to have another
+ # one with the same ordering key created immediately afterward.
+ if self._state == _OrderedSequencerStatus.FINISHED:
+ self._state = _OrderedSequencerStatus.ACCEPTING_MESSAGES
+
+ if self._state == _OrderedSequencerStatus.STOPPED:
+ raise RuntimeError("Cannot publish on a stopped sequencer.")
+
+ assert (
+ self._state == _OrderedSequencerStatus.ACCEPTING_MESSAGES
+ ), "Publish is only allowed in accepting-messages state."
+
+ if not self._ordered_batches:
+ new_batch = self._create_batch(
+ commit_retry=retry, commit_timeout=timeout
+ )
+ self._ordered_batches.append(new_batch)
+
+ batch = self._ordered_batches[-1]
+ future = batch.publish(message)
+ while future is None:
+ batch = self._create_batch(commit_retry=retry, commit_timeout=timeout)
+ self._ordered_batches.append(batch)
+ future = batch.publish(message)
+
+ return future
+
+ # Used only for testing.
+ def _set_batch(self, batch: "_batch.thread.Batch") -> None:
+ self._ordered_batches = collections.deque([batch])
+
+ # Used only for testing.
+ def _set_batches(self, batches: Iterable["_batch.thread.Batch"]) -> None:
+ self._ordered_batches = collections.deque(batches)
+
+ # Used only for testing.
+ def _get_batches(self) -> Sequence["_batch.thread.Batch"]:
+ return self._ordered_batches
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/unordered_sequencer.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/unordered_sequencer.py
new file mode 100644
index 000000000000..7d57aa8218b9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/_sequencer/unordered_sequencer.py
@@ -0,0 +1,165 @@
+# Copyright 2019, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import typing
+from typing import Optional
+
+from google.api_core import gapic_v1
+
+from google.cloud.pubsub_v1.publisher._sequencer import base
+from google.pubsub_v1 import types as gapic_types
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1.publisher import _batch
+ from google.cloud.pubsub_v1.publisher import futures
+ from google.cloud.pubsub_v1.publisher.client import Client as PublisherClient
+ from google.pubsub_v1.services.publisher.client import OptionalRetry
+
+ from google.cloud.pubsub_v1 import types
+
+
+class UnorderedSequencer(base.Sequencer):
+ """Sequences messages into batches for one topic without any ordering.
+
+ Public methods are NOT thread-safe.
+ """
+
+ def __init__(self, client: "PublisherClient", topic: str):
+ self._client = client
+ self._topic = topic
+ self._current_batch: Optional["_batch.thread.Batch"] = None
+ self._stopped = False
+
+ def is_finished(self) -> bool:
+ """Whether the sequencer is finished and should be cleaned up.
+
+ Returns:
+ Whether the sequencer is finished and should be cleaned up.
+ """
+ # TODO: Implement. Not implementing yet because of possible performance
+ # impact due to extra locking required. This does mean that
+ # UnorderedSequencers don't get cleaned up, but this is the same as
+ # previously existing behavior.
+ return False
+
+ def stop(self) -> None:
+ """Stop the sequencer.
+
+ Subsequent publishes will fail.
+
+ Raises:
+ RuntimeError:
+ If called after stop() has already been called.
+ """
+ if self._stopped:
+ raise RuntimeError("Unordered sequencer already stopped.")
+ self.commit()
+ self._stopped = True
+
+ def commit(self) -> None:
+ """Commit the batch.
+
+ Raises:
+ RuntimeError:
+ If called after stop() has already been called.
+ """
+ if self._stopped:
+ raise RuntimeError("Unordered sequencer already stopped.")
+ if self._current_batch:
+ self._current_batch.commit()
+
+ # At this point, we lose track of the old batch, but we don't
+ # care since we just committed it.
+ # Setting this to None guarantees the next publish() creates a new
+ # batch.
+ self._current_batch = None
+
+ def unpause(self) -> typing.NoReturn:
+ """Not relevant for this class."""
+ raise NotImplementedError
+
+ def _create_batch(
+ self,
+ commit_retry: "OptionalRetry" = gapic_v1.method.DEFAULT,
+ commit_timeout: "types.OptionalTimeout" = gapic_v1.method.DEFAULT,
+ ) -> "_batch.thread.Batch":
+ """Create a new batch using the client's batch class and other stored
+ settings.
+
+ Args:
+ commit_retry:
+ The retry settings to apply when publishing the batch.
+ commit_timeout:
+ The timeout to apply when publishing the batch.
+ """
+ return self._client._batch_class(
+ client=self._client,
+ topic=self._topic,
+ settings=self._client.batch_settings,
+ batch_done_callback=None,
+ commit_when_full=True,
+ commit_retry=commit_retry,
+ commit_timeout=commit_timeout,
+ )
+
+ def publish(
+ self,
+ message: gapic_types.PubsubMessage,
+ retry: "OptionalRetry" = gapic_v1.method.DEFAULT,
+ timeout: "types.OptionalTimeout" = gapic_v1.method.DEFAULT,
+ ) -> "futures.Future":
+ """Batch message into existing or new batch.
+
+ Args:
+ message:
+ The Pub/Sub message.
+ retry:
+ The retry settings to apply when publishing the message.
+ timeout:
+ The timeout to apply when publishing the message.
+
+ Returns:
+ An object conforming to the :class:`~concurrent.futures.Future` interface.
+ The future tracks the publishing status of the message.
+
+ Raises:
+ RuntimeError:
+ If called after stop() has already been called.
+
+ pubsub_v1.publisher.exceptions.MessageTooLargeError: If publishing
+ the ``message`` would exceed the max size limit on the backend.
+ """
+ if self._stopped:
+ raise RuntimeError("Unordered sequencer already stopped.")
+
+ if not self._current_batch:
+ newbatch = self._create_batch(commit_retry=retry, commit_timeout=timeout)
+ self._current_batch = newbatch
+
+ batch = self._current_batch
+ future = None
+ while future is None:
+ # Might throw MessageTooLargeError
+ future = batch.publish(message)
+ # batch is full, triggering commit_when_full
+ if future is None:
+ batch = self._create_batch(commit_retry=retry, commit_timeout=timeout)
+ # At this point, we lose track of the old batch, but we don't
+ # care since it's already committed (because it was full.)
+ self._current_batch = batch
+ return future
+
+ # Used only for testing.
+ def _set_batch(self, batch: "_batch.thread.Batch") -> None:
+ self._current_batch = batch
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
new file mode 100644
index 000000000000..e3266e57f854
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
@@ -0,0 +1,519 @@
+# Copyright 2019, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import copy
+import logging
+import os
+import pkg_resources
+import threading
+import time
+import typing
+from typing import Any, Dict, Optional, Sequence, Tuple, Type, Union
+import warnings
+
+from google.api_core import gapic_v1
+from google.auth.credentials import AnonymousCredentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+from google.cloud.pubsub_v1 import types
+from google.cloud.pubsub_v1.publisher import exceptions
+from google.cloud.pubsub_v1.publisher import futures
+from google.cloud.pubsub_v1.publisher._batch import thread
+from google.cloud.pubsub_v1.publisher._sequencer import ordered_sequencer
+from google.cloud.pubsub_v1.publisher._sequencer import unordered_sequencer
+from google.cloud.pubsub_v1.publisher.flow_controller import FlowController
+from google.pubsub_v1 import types as gapic_types
+from google.pubsub_v1.services.publisher import client as publisher_client
+
+try:
+ __version__ = pkg_resources.get_distribution("google-cloud-pubsub").version
+except pkg_resources.DistributionNotFound:
+ # Distribution might not be available if we are not running from within a
+ # PIP package.
+ __version__ = "0.0"
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud import pubsub_v1
+ from google.cloud.pubsub_v1.publisher import _batch
+ from google.pubsub_v1.services.publisher.client import OptionalRetry
+ from google.pubsub_v1.types import pubsub as pubsub_types
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+_raw_proto_pubbsub_message = gapic_types.PubsubMessage.pb()
+
+SequencerType = Union[
+ ordered_sequencer.OrderedSequencer, unordered_sequencer.UnorderedSequencer
+]
+
+
+class Client(publisher_client.PublisherClient):
+ """A publisher client for Google Cloud Pub/Sub.
+
+ This creates an object that is capable of publishing messages.
+ Generally, you can instantiate this client with no arguments, and you
+ get sensible defaults.
+
+ Args:
+ batch_settings:
+ The settings for batch publishing.
+ publisher_options:
+ The options for the publisher client. Note that enabling message ordering
+ will override the publish retry timeout to be infinite.
+ kwargs:
+ Any additional arguments provided are sent as keyword arguments to the
+ underlying
+ :class:`~google.cloud.pubsub_v1.gapic.publisher_client.PublisherClient`.
+ Generally you should not need to set additional keyword
+ arguments. Regional endpoints can be set via ``client_options`` that
+ takes a single key-value pair that defines the endpoint.
+
+ Example:
+
+ .. code-block:: python
+
+ from google.cloud import pubsub_v1
+
+ publisher_client = pubsub_v1.PublisherClient(
+ # Optional
+ batch_settings = pubsub_v1.types.BatchSettings(
+ max_bytes=1024, # One kilobyte
+ max_latency=1, # One second
+ ),
+
+ # Optional
+ publisher_options = pubsub_v1.types.PublisherOptions(
+ enable_message_ordering=False,
+ flow_control=pubsub_v1.types.PublishFlowControl(
+ message_limit=2000,
+ limit_exceeded_behavior=pubsub_v1.types.LimitExceededBehavior.BLOCK,
+ ),
+ ),
+
+ # Optional
+ client_options = {
+ "api_endpoint": REGIONAL_ENDPOINT
+ }
+ )
+ """
+
+ def __init__(
+ self,
+ batch_settings: Union[types.BatchSettings, Sequence] = (),
+ publisher_options: Union[types.PublisherOptions, Sequence] = (),
+ **kwargs: Any,
+ ):
+ assert (
+ type(batch_settings) is types.BatchSettings or len(batch_settings) == 0
+ ), "batch_settings must be of type BatchSettings or an empty sequence."
+ assert (
+ type(publisher_options) is types.PublisherOptions
+ or len(publisher_options) == 0
+ ), "publisher_options must be of type PublisherOptions or an empty sequence."
+
+ # Sanity check: Is our goal to use the emulator?
+ # If so, create a grpc insecure channel with the emulator host
+ # as the target.
+ if os.environ.get("PUBSUB_EMULATOR_HOST"):
+ kwargs["client_options"] = {
+ "api_endpoint": os.environ.get("PUBSUB_EMULATOR_HOST")
+ }
+ kwargs["credentials"] = AnonymousCredentials()
+
+ # For a transient failure, retry publishing the message infinitely.
+ self.publisher_options = types.PublisherOptions(*publisher_options)
+ self._enable_message_ordering = self.publisher_options[0]
+
+ # Add the metrics headers, and instantiate the underlying GAPIC
+ # client.
+ super().__init__(**kwargs)
+ self._target = self._transport._host
+ self._batch_class = thread.Batch
+ self.batch_settings = types.BatchSettings(*batch_settings)
+
+ # The batches on the publisher client are responsible for holding
+ # messages. One batch exists for each topic.
+ self._batch_lock = self._batch_class.make_lock()
+ # (topic, ordering_key) => sequencers object
+ self._sequencers: Dict[Tuple[str, str], SequencerType] = {}
+ self._is_stopped = False
+ # Thread created to commit all sequencers after a timeout.
+ self._commit_thread: Optional[threading.Thread] = None
+
+ # The object controlling the message publishing flow
+ self._flow_controller = FlowController(self.publisher_options.flow_control)
+
+ @classmethod
+ def from_service_account_file( # type: ignore[override]
+ cls,
+ filename: str,
+ batch_settings: Union[types.BatchSettings, Sequence] = (),
+ **kwargs: Any,
+ ) -> "Client":
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename:
+ The path to the service account private key JSON file.
+ batch_settings:
+ The settings for batch publishing.
+ kwargs:
+ Additional arguments to pass to the constructor.
+
+ Returns:
+ A Publisher instance that is the constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_file(filename)
+ kwargs["credentials"] = credentials
+ return cls(batch_settings, **kwargs)
+
+ from_service_account_json = from_service_account_file # type: ignore[assignment]
+
+ @property
+ def target(self) -> str:
+ """Return the target (where the API is).
+
+ Returns:
+ The location of the API.
+ """
+ return self._target
+
+ @property
+ def api(self):
+ """The underlying gapic API client.
+
+ .. versionchanged:: 2.10.0
+ Instead of a GAPIC ``PublisherClient`` client instance, this property is a
+ proxy object to it with the same interface.
+
+ .. deprecated:: 2.10.0
+ Use the GAPIC methods and properties on the client instance directly
+ instead of through the :attr:`api` attribute.
+ """
+ msg = (
+ 'The "api" property only exists for backward compatibility, access its '
+ 'attributes directly thorugh the client instance (e.g. "client.foo" '
+ 'instead of "client.api.foo").'
+ )
+ warnings.warn(msg, category=DeprecationWarning)
+ return super()
+
+ def _get_or_create_sequencer(self, topic: str, ordering_key: str) -> SequencerType:
+ """Get an existing sequencer or create a new one given the (topic,
+ ordering_key) pair.
+ """
+ sequencer_key = (topic, ordering_key)
+ sequencer = self._sequencers.get(sequencer_key)
+ if sequencer is None:
+ if ordering_key == "":
+ sequencer = unordered_sequencer.UnorderedSequencer(self, topic)
+ else:
+ sequencer = ordered_sequencer.OrderedSequencer(
+ self, topic, ordering_key
+ )
+ self._sequencers[sequencer_key] = sequencer
+
+ return sequencer
+
+ def resume_publish(self, topic: str, ordering_key: str) -> None:
+ """Resume publish on an ordering key that has had unrecoverable errors.
+
+ Args:
+ topic: The topic to publish messages to.
+ ordering_key: A string that identifies related messages for which
+ publish order should be respected.
+
+ Raises:
+ RuntimeError:
+ If called after publisher has been stopped by a `stop()` method
+ call.
+ ValueError:
+ If the topic/ordering key combination has not been seen before
+ by this client.
+ """
+ with self._batch_lock:
+ if self._is_stopped:
+ raise RuntimeError("Cannot resume publish on a stopped publisher.")
+
+ if not self._enable_message_ordering:
+ raise ValueError(
+ "Cannot resume publish on a topic/ordering key if ordering "
+ "is not enabled."
+ )
+
+ sequencer_key = (topic, ordering_key)
+ sequencer = self._sequencers.get(sequencer_key)
+ if sequencer is None:
+ _LOGGER.debug(
+ "Error: The topic/ordering key combination has not "
+ "been seen before."
+ )
+ else:
+ sequencer.unpause()
+
+ def _gapic_publish(self, *args, **kwargs) -> "pubsub_types.PublishResponse":
+ """Call the GAPIC public API directly."""
+ return super().publish(*args, **kwargs)
+
+ def publish( # type: ignore[override]
+ self,
+ topic: str,
+ data: bytes,
+ ordering_key: str = "",
+ retry: "OptionalRetry" = gapic_v1.method.DEFAULT,
+ timeout: "types.OptionalTimeout" = gapic_v1.method.DEFAULT,
+ **attrs: Union[bytes, str],
+ ) -> "pubsub_v1.publisher.futures.Future":
+ """Publish a single message.
+
+ .. note::
+ Messages in Pub/Sub are blobs of bytes. They are *binary* data,
+ not text. You must send data as a bytestring
+ (``bytes`` in Python 3; ``str`` in Python 2), and this library
+ will raise an exception if you send a text string.
+
+ The reason that this is so important (and why we do not try to
+ coerce for you) is because Pub/Sub is also platform independent
+ and there is no way to know how to decode messages properly on
+ the other side; therefore, encoding and decoding is a required
+ exercise for the developer.
+
+ Add the given message to this object; this will cause it to be
+ published once the batch either has enough messages or a sufficient
+ period of time has elapsed.
+ This method may block if LimitExceededBehavior.BLOCK is used in the
+ flow control settings.
+
+ Example:
+ >>> from google.cloud import pubsub_v1
+ >>> client = pubsub_v1.PublisherClient()
+ >>> topic = client.topic_path('[PROJECT]', '[TOPIC]')
+ >>> data = b'The rain in Wales falls mainly on the snails.'
+ >>> response = client.publish(topic, data, username='guido')
+
+ Args:
+ topic: The topic to publish messages to.
+ data: A bytestring representing the message body. This
+ must be a bytestring.
+ ordering_key: A string that identifies related messages for which
+ publish order should be respected. Message ordering must be
+ enabled for this client to use this feature.
+ retry:
+ Designation of what errors, if any, should be retried. If `ordering_key`
+ is specified, the total retry deadline will be changed to "infinity".
+ If given, it overides any retry passed into the client through
+ the ``publisher_options`` argument.
+ timeout:
+ The timeout for the RPC request. Can be used to override any timeout
+ passed in through ``publisher_options`` when instantiating the client.
+
+ attrs: A dictionary of attributes to be
+ sent as metadata. (These may be text strings or byte strings.)
+
+ Returns:
+ A :class:`~google.cloud.pubsub_v1.publisher.futures.Future`
+ instance that conforms to Python Standard library's
+ :class:`~concurrent.futures.Future` interface (but not an
+ instance of that class).
+
+ Raises:
+ RuntimeError:
+ If called after publisher has been stopped by a `stop()` method
+ call.
+
+ pubsub_v1.publisher.exceptions.MessageTooLargeError: If publishing
+ the ``message`` would exceed the max size limit on the backend.
+ """
+ # Sanity check: Is the data being sent as a bytestring?
+ # If it is literally anything else, complain loudly about it.
+ if not isinstance(data, bytes):
+ raise TypeError(
+ "Data being published to Pub/Sub must be sent as a bytestring."
+ )
+
+ if not self._enable_message_ordering and ordering_key != "":
+ raise ValueError(
+ "Cannot publish a message with an ordering key when message "
+ "ordering is not enabled."
+ )
+
+ # Coerce all attributes to text strings.
+ for k, v in copy.copy(attrs).items():
+ if isinstance(v, str):
+ continue
+ if isinstance(v, bytes):
+ attrs[k] = v.decode("utf-8")
+ continue
+ raise TypeError(
+ "All attributes being published to Pub/Sub must "
+ "be sent as text strings."
+ )
+
+ # Create the Pub/Sub message object. For performance reasons, the message
+ # should be constructed by directly using the raw protobuf class, and only
+ # then wrapping it into the higher-level PubsubMessage class.
+ vanilla_pb = _raw_proto_pubbsub_message(
+ data=data, ordering_key=ordering_key, attributes=attrs
+ )
+ message = gapic_types.PubsubMessage.wrap(vanilla_pb)
+
+ # Messages should go through flow control to prevent excessive
+ # queuing on the client side (depending on the settings).
+ try:
+ self._flow_controller.add(message)
+ except exceptions.FlowControlLimitError as exc:
+ future = futures.Future()
+ future.set_exception(exc)
+ return future
+
+ def on_publish_done(future):
+ self._flow_controller.release(message)
+
+ if retry is gapic_v1.method.DEFAULT: # if custom retry not passed in
+ retry = self.publisher_options.retry
+
+ if timeout is gapic_v1.method.DEFAULT: # if custom timeout not passed in
+ timeout = self.publisher_options.timeout
+
+ with self._batch_lock:
+ if self._is_stopped:
+ raise RuntimeError("Cannot publish on a stopped publisher.")
+
+ # Set retry timeout to "infinite" when message ordering is enabled.
+ # Note that this then also impacts messages added with an empty
+ # ordering key.
+ if self._enable_message_ordering:
+ if retry is gapic_v1.method.DEFAULT:
+ # use the default retry for the publish GRPC method as a base
+ transport = self._transport
+ base_retry = transport._wrapped_methods[transport.publish]._retry
+ retry = base_retry.with_deadline(2.0**32)
+ else:
+ retry = retry.with_deadline(2.0**32)
+
+ # Delegate the publishing to the sequencer.
+ sequencer = self._get_or_create_sequencer(topic, ordering_key)
+ future = sequencer.publish(message, retry=retry, timeout=timeout)
+ future.add_done_callback(on_publish_done)
+
+ # Create a timer thread if necessary to enforce the batching
+ # timeout.
+ self._ensure_commit_timer_runs_no_lock()
+
+ return future
+
+ def ensure_cleanup_and_commit_timer_runs(self) -> None:
+ """Ensure a cleanup/commit timer thread is running.
+
+ If a cleanup/commit timer thread is already running, this does nothing.
+ """
+ with self._batch_lock:
+ self._ensure_commit_timer_runs_no_lock()
+
+ def _ensure_commit_timer_runs_no_lock(self) -> None:
+ """Ensure a commit timer thread is running, without taking
+ _batch_lock.
+
+ _batch_lock must be held before calling this method.
+ """
+ if not self._commit_thread and self.batch_settings.max_latency < float("inf"):
+ self._start_commit_thread()
+
+ def _start_commit_thread(self) -> None:
+ """Start a new thread to actually wait and commit the sequencers."""
+ # NOTE: If the thread is *not* a daemon, a memory leak exists due to a CPython issue.
+ # https://github.com/googleapis/python-pubsub/issues/395#issuecomment-829910303
+ # https://github.com/googleapis/python-pubsub/issues/395#issuecomment-830092418
+ self._commit_thread = threading.Thread(
+ name="Thread-PubSubBatchCommitter",
+ target=self._wait_and_commit_sequencers,
+ daemon=True,
+ )
+ self._commit_thread.start()
+
+ def _wait_and_commit_sequencers(self) -> None:
+ """Wait up to the batching timeout, and commit all sequencers."""
+ # Sleep for however long we should be waiting.
+ time.sleep(self.batch_settings.max_latency)
+ _LOGGER.debug("Commit thread is waking up")
+
+ with self._batch_lock:
+ if self._is_stopped:
+ return
+ self._commit_sequencers()
+ self._commit_thread = None
+
+ def _commit_sequencers(self) -> None:
+ """Clean up finished sequencers and commit the rest."""
+ finished_sequencer_keys = [
+ key
+ for key, sequencer in self._sequencers.items()
+ if sequencer.is_finished()
+ ]
+ for sequencer_key in finished_sequencer_keys:
+ del self._sequencers[sequencer_key]
+
+ for sequencer in self._sequencers.values():
+ sequencer.commit()
+
+ def stop(self) -> None:
+ """Immediately publish all outstanding messages.
+
+ Asynchronously sends all outstanding messages and
+ prevents future calls to `publish()`. Method should
+ be invoked prior to deleting this `Client()` object
+ in order to ensure that no pending messages are lost.
+
+ .. note::
+
+ This method is non-blocking. Use `Future()` objects
+ returned by `publish()` to make sure all publish
+ requests completed, either in success or error.
+
+ Raises:
+ RuntimeError:
+ If called after publisher has been stopped by a `stop()` method
+ call.
+ """
+ with self._batch_lock:
+ if self._is_stopped:
+ raise RuntimeError("Cannot stop a publisher already stopped.")
+
+ self._is_stopped = True
+
+ for sequencer in self._sequencers.values():
+ sequencer.stop()
+
+ # Used only for testing.
+ def _set_batch(
+ self, topic: str, batch: "_batch.thread.Batch", ordering_key: str = ""
+ ) -> None:
+ sequencer = self._get_or_create_sequencer(topic, ordering_key)
+ sequencer._set_batch(batch)
+
+ # Used only for testing.
+ def _set_batch_class(self, batch_class: Type) -> None:
+ self._batch_class = batch_class
+
+ # Used only for testing.
+ def _set_sequencer(
+ self, topic: str, sequencer: SequencerType, ordering_key: str = ""
+ ) -> None:
+ sequencer_key = (topic, ordering_key)
+ self._sequencers[sequencer_key] = sequencer
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/exceptions.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/exceptions.py
new file mode 100644
index 000000000000..f2b65299e1f2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/exceptions.py
@@ -0,0 +1,51 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+from google.api_core.exceptions import GoogleAPICallError
+from google.cloud.pubsub_v1.exceptions import TimeoutError
+
+
+class PublishError(GoogleAPICallError):
+ pass
+
+
+class MessageTooLargeError(ValueError):
+ """Attempt to publish a message that would exceed the server max size limit."""
+
+
+class PublishToPausedOrderingKeyException(Exception):
+ """Publish attempted to paused ordering key. To resume publishing, call
+ the resumePublish method on the publisher Client object with this
+ ordering key. Ordering keys are paused if an unrecoverable error
+ occurred during publish of a batch for that key.
+ """
+
+ def __init__(self, ordering_key: str):
+ self.ordering_key = ordering_key
+ super(PublishToPausedOrderingKeyException, self).__init__()
+
+
+class FlowControlLimitError(Exception):
+ """An action resulted in exceeding the flow control limits."""
+
+
+__all__ = (
+ "FlowControlLimitError",
+ "MessageTooLargeError",
+ "PublishError",
+ "TimeoutError",
+ "PublishToPausedOrderingKeyException",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/flow_controller.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/flow_controller.py
new file mode 100644
index 000000000000..baf6ba8ff838
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/flow_controller.py
@@ -0,0 +1,313 @@
+# Copyright 2020, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from collections import OrderedDict
+import logging
+import threading
+from typing import Dict, Optional, Type
+import warnings
+
+from google.cloud.pubsub_v1 import types
+from google.cloud.pubsub_v1.publisher import exceptions
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+MessageType = Type[types.PubsubMessage] # type: ignore
+
+
+class _QuantityReservation:
+ """A (partial) reservation of quantifiable resources."""
+
+ def __init__(self, bytes_reserved: int, bytes_needed: int, has_slot: bool):
+ self.bytes_reserved = bytes_reserved
+ self.bytes_needed = bytes_needed
+ self.has_slot = has_slot
+
+ def __repr__(self):
+ return (
+ f"{type(self).__name__}("
+ f"bytes_reserved={self.bytes_reserved}, "
+ f"bytes_needed={self.bytes_needed}, "
+ f"has_slot={self.has_slot})"
+ )
+
+
+class FlowController(object):
+ """A class used to control the flow of messages passing through it.
+
+ Args:
+ settings: Desired flow control configuration.
+ """
+
+ def __init__(self, settings: types.PublishFlowControl):
+ self._settings = settings
+
+ # Load statistics. They represent the number of messages added, but not
+ # yet released (and their total size).
+ self._message_count = 0
+ self._total_bytes = 0
+
+ # A FIFO queue of threads blocked on adding a message that also tracks their
+ # reservations of available flow control bytes and message slots.
+ # Only relevant if the configured limit exceeded behavior is BLOCK.
+ self._waiting: Dict[threading.Thread, _QuantityReservation] = OrderedDict()
+
+ self._reserved_bytes = 0
+ self._reserved_slots = 0
+
+ # The lock is used to protect all internal state (message and byte count,
+ # waiting threads to add, etc.).
+ self._operational_lock = threading.Lock()
+
+ # The condition for blocking the flow if capacity is exceeded.
+ self._has_capacity = threading.Condition(lock=self._operational_lock)
+
+ def add(self, message: MessageType) -> None:
+ """Add a message to flow control.
+
+ Adding a message updates the internal load statistics, and an action is
+ taken if these limits are exceeded (depending on the flow control settings).
+
+ Args:
+ message:
+ The message entering the flow control.
+
+ Raises:
+ :exception:`~pubsub_v1.publisher.exceptions.FlowControlLimitError`:
+ Raised when the desired action is
+ :attr:`~google.cloud.pubsub_v1.types.LimitExceededBehavior.ERROR` and
+ the message would exceed flow control limits, or when the desired action
+ is :attr:`~google.cloud.pubsub_v1.types.LimitExceededBehavior.BLOCK` and
+ the message would block forever against the flow control limits.
+ """
+ if self._settings.limit_exceeded_behavior == types.LimitExceededBehavior.IGNORE:
+ return
+
+ with self._operational_lock:
+ if not self._would_overflow(message):
+ self._message_count += 1
+ self._total_bytes += message._pb.ByteSize()
+ return
+
+ # Adding a message would overflow, react.
+ if (
+ self._settings.limit_exceeded_behavior
+ == types.LimitExceededBehavior.ERROR
+ ):
+ # Raising an error means rejecting a message, thus we do not
+ # add anything to the existing load, but we do report the would-be
+ # load if we accepted the message.
+ load_info = self._load_info(
+ message_count=self._message_count + 1,
+ total_bytes=self._total_bytes + message._pb.ByteSize(),
+ )
+ error_msg = "Flow control limits would be exceeded - {}.".format(
+ load_info
+ )
+ raise exceptions.FlowControlLimitError(error_msg)
+
+ assert (
+ self._settings.limit_exceeded_behavior
+ == types.LimitExceededBehavior.BLOCK
+ )
+
+ # Sanity check - if a message exceeds total flow control limits all
+ # by itself, it would block forever, thus raise error.
+ if (
+ message._pb.ByteSize() > self._settings.byte_limit
+ or self._settings.message_limit < 1
+ ):
+ load_info = self._load_info(
+ message_count=1, total_bytes=message._pb.ByteSize()
+ )
+ error_msg = (
+ "Total flow control limits too low for the message, "
+ "would block forever - {}.".format(load_info)
+ )
+ raise exceptions.FlowControlLimitError(error_msg)
+
+ current_thread = threading.current_thread()
+
+ while self._would_overflow(message):
+ if current_thread not in self._waiting:
+ reservation = _QuantityReservation(
+ bytes_reserved=0,
+ bytes_needed=message._pb.ByteSize(),
+ has_slot=False,
+ )
+ self._waiting[current_thread] = reservation # Will be placed last.
+
+ _LOGGER.debug(
+ "Blocking until there is enough free capacity in the flow - "
+ "{}.".format(self._load_info())
+ )
+
+ self._has_capacity.wait()
+
+ _LOGGER.debug(
+ "Woke up from waiting on free capacity in the flow - "
+ "{}.".format(self._load_info())
+ )
+
+ # Message accepted, increase the load and remove thread stats.
+ self._message_count += 1
+ self._total_bytes += message._pb.ByteSize()
+ self._reserved_bytes -= self._waiting[current_thread].bytes_reserved
+ self._reserved_slots -= 1
+ del self._waiting[current_thread]
+
+ def release(self, message: MessageType) -> None:
+ """Release a mesage from flow control.
+
+ Args:
+ message:
+ The message entering the flow control.
+ """
+ if self._settings.limit_exceeded_behavior == types.LimitExceededBehavior.IGNORE:
+ return
+
+ with self._operational_lock:
+ # Releasing a message decreases the load.
+ self._message_count -= 1
+ self._total_bytes -= message._pb.ByteSize()
+
+ if self._message_count < 0 or self._total_bytes < 0:
+ warnings.warn(
+ "Releasing a message that was never added or already released.",
+ category=RuntimeWarning,
+ stacklevel=2,
+ )
+ self._message_count = max(0, self._message_count)
+ self._total_bytes = max(0, self._total_bytes)
+
+ self._distribute_available_capacity()
+
+ # If at least one thread waiting to add() can be unblocked, wake them up.
+ if self._ready_to_unblock():
+ _LOGGER.debug("Notifying threads waiting to add messages to flow.")
+ self._has_capacity.notify_all()
+
+ def _distribute_available_capacity(self) -> None:
+ """Distribute available capacity among the waiting threads in FIFO order.
+
+ The method assumes that the caller has obtained ``_operational_lock``.
+ """
+ available_slots = (
+ self._settings.message_limit - self._message_count - self._reserved_slots
+ )
+ available_bytes = (
+ self._settings.byte_limit - self._total_bytes - self._reserved_bytes
+ )
+
+ for reservation in self._waiting.values():
+ if available_slots <= 0 and available_bytes <= 0:
+ break # Santa is now empty-handed, better luck next time.
+
+ # Distribute any free slots.
+ if available_slots > 0 and not reservation.has_slot:
+ reservation.has_slot = True
+ self._reserved_slots += 1
+ available_slots -= 1
+
+ # Distribute any free bytes.
+ if available_bytes <= 0:
+ continue
+
+ bytes_still_needed = reservation.bytes_needed - reservation.bytes_reserved
+
+ if bytes_still_needed < 0: # Sanity check for any internal inconsistencies.
+ msg = "Too many bytes reserved: {} / {}".format(
+ reservation.bytes_reserved, reservation.bytes_needed
+ )
+ warnings.warn(msg, category=RuntimeWarning)
+ bytes_still_needed = 0
+
+ can_give = min(bytes_still_needed, available_bytes)
+ reservation.bytes_reserved += can_give
+ self._reserved_bytes += can_give
+ available_bytes -= can_give
+
+ def _ready_to_unblock(self) -> bool:
+ """Determine if any of the threads waiting to add a message can proceed.
+
+ The method assumes that the caller has obtained ``_operational_lock``.
+ """
+ if self._waiting:
+ # It's enough to only check the head of the queue, because FIFO
+ # distribution of any free capacity.
+ first_reservation = next(iter(self._waiting.values()))
+ return (
+ first_reservation.bytes_reserved >= first_reservation.bytes_needed
+ and first_reservation.has_slot
+ )
+
+ return False
+
+ def _would_overflow(self, message: MessageType) -> bool:
+ """Determine if accepting a message would exceed flow control limits.
+
+ The method assumes that the caller has obtained ``_operational_lock``.
+
+ Args:
+ message: The message entering the flow control.
+ """
+ reservation = self._waiting.get(threading.current_thread())
+
+ if reservation:
+ enough_reserved = reservation.bytes_reserved >= reservation.bytes_needed
+ has_slot = reservation.has_slot
+ else:
+ enough_reserved = False
+ has_slot = False
+
+ bytes_taken = self._total_bytes + self._reserved_bytes + message._pb.ByteSize()
+ size_overflow = bytes_taken > self._settings.byte_limit and not enough_reserved
+
+ msg_count_overflow = not has_slot and (
+ (self._message_count + self._reserved_slots + 1)
+ > self._settings.message_limit
+ )
+
+ return size_overflow or msg_count_overflow
+
+ def _load_info(
+ self, message_count: Optional[int] = None, total_bytes: Optional[int] = None
+ ) -> str:
+ """Return the current flow control load information.
+
+ The caller can optionally adjust some of the values to fit its reporting
+ needs.
+
+ The method assumes that the caller has obtained ``_operational_lock``.
+
+ Args:
+ message_count:
+ The value to override the current message count with.
+ total_bytes:
+ The value to override the current total bytes with.
+ """
+ if message_count is None:
+ message_count = self._message_count
+
+ if total_bytes is None:
+ total_bytes = self._total_bytes
+
+ return (
+ f"messages: {message_count} / {self._settings.message_limit} "
+ f"(reserved: {self._reserved_slots}), "
+ f"bytes: {total_bytes} / {self._settings.byte_limit} "
+ f"(reserved: {self._reserved_bytes})"
+ )
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
new file mode 100644
index 000000000000..c7cc66f18d2c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
@@ -0,0 +1,83 @@
+# Copyright 2019, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import typing
+from typing import Any, Callable, Union
+
+from google.cloud.pubsub_v1 import futures
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud import pubsub_v1
+
+
+class Future(futures.Future):
+ """This future object is returned from asychronous Pub/Sub publishing
+ calls.
+
+ Calling :meth:`result` will resolve the future by returning the message
+ ID, unless an error occurs.
+ """
+
+ def cancel(self) -> bool:
+ """Actions in Pub/Sub generally may not be canceled.
+
+ This method always returns ``False``.
+ """
+ return False
+
+ def cancelled(self) -> bool:
+ """Actions in Pub/Sub generally may not be canceled.
+
+ This method always returns ``False``.
+ """
+ return False
+
+ def result(self, timeout: Union[int, float] = None) -> str:
+ """Return the message ID or raise an exception.
+
+ This blocks until the message has been published successfully and
+ returns the message ID unless an exception is raised.
+
+ Args:
+ timeout: The number of seconds before this call
+ times out and raises TimeoutError.
+
+ Returns:
+ The message ID.
+
+ Raises:
+ concurrent.futures.TimeoutError: If the request times out.
+ Exception: For undefined exceptions in the underlying
+ call execution.
+ """
+ return super().result(timeout=timeout)
+
+ # This exists to make the type checkers happy.
+ def add_done_callback(
+ self, callback: Callable[["pubsub_v1.publisher.futures.Future"], Any]
+ ) -> None:
+ """Attach a callable that will be called when the future finishes.
+
+ Args:
+ callback:
+ A callable that will be called with this future as its only
+ argument when the future completes or is cancelled. The callable
+ will always be called by a thread in the same process in which
+ it was added. If the future has already completed or been
+ cancelled then the callable will be called immediately. These
+ callables are called in the order that they were added.
+ """
+ return super().add_done_callback(callback) # type: ignore
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/__init__.py
new file mode 100644
index 000000000000..a444c3ea7571
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/__init__.py
@@ -0,0 +1,20 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+from google.cloud.pubsub_v1.subscriber.client import Client
+
+
+__all__ = ("Client",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/dispatcher.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/dispatcher.py
new file mode 100644
index 000000000000..ed2f5d21777a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/dispatcher.py
@@ -0,0 +1,406 @@
+# Copyright 2017, Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+from __future__ import division
+
+import functools
+import itertools
+import logging
+import math
+import time
+import threading
+import typing
+from typing import List, Optional, Sequence, Union
+import warnings
+from google.api_core.retry import exponential_sleep_generator
+
+from google.cloud.pubsub_v1.subscriber._protocol import helper_threads
+from google.cloud.pubsub_v1.subscriber._protocol import requests
+from google.cloud.pubsub_v1.subscriber.exceptions import (
+ AcknowledgeStatus,
+)
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ import queue
+ from google.cloud.pubsub_v1.subscriber._protocol.streaming_pull_manager import (
+ StreamingPullManager,
+ )
+
+
+RequestItem = Union[
+ requests.AckRequest,
+ requests.DropRequest,
+ requests.LeaseRequest,
+ requests.ModAckRequest,
+ requests.NackRequest,
+]
+
+
+_LOGGER = logging.getLogger(__name__)
+_CALLBACK_WORKER_NAME = "Thread-CallbackRequestDispatcher"
+
+
+_MAX_BATCH_SIZE = 100
+"""The maximum number of requests to process and dispatch at a time."""
+
+_MAX_BATCH_LATENCY = 0.01
+"""The maximum amount of time in seconds to wait for additional request items
+before processing the next batch of requests."""
+
+_ACK_IDS_BATCH_SIZE = 1000
+"""The maximum number of ACK IDs to send in a single StreamingPullRequest.
+"""
+
+_MIN_EXACTLY_ONCE_DELIVERY_ACK_MODACK_RETRY_DURATION_SECS = 1
+"""The time to wait for the first retry of failed acks and modacks when exactly-once
+delivery is enabled."""
+
+_MAX_EXACTLY_ONCE_DELIVERY_ACK_MODACK_RETRY_DURATION_SECS = 10 * 60
+"""The maximum amount of time in seconds to retry failed acks and modacks when
+exactly-once delivery is enabled."""
+
+
+class Dispatcher(object):
+ def __init__(self, manager: "StreamingPullManager", queue: "queue.Queue"):
+ self._manager = manager
+ self._queue = queue
+ self._thread: Optional[threading.Thread] = None
+ self._operational_lock = threading.Lock()
+
+ def start(self) -> None:
+ """Start a thread to dispatch requests queued up by callbacks.
+
+ Spawns a thread to run :meth:`dispatch_callback`.
+ """
+ with self._operational_lock:
+ if self._thread is not None:
+ raise ValueError("Dispatcher is already running.")
+
+ worker = helper_threads.QueueCallbackWorker(
+ self._queue,
+ self.dispatch_callback,
+ max_items=_MAX_BATCH_SIZE,
+ max_latency=_MAX_BATCH_LATENCY,
+ )
+ # Create and start the helper thread.
+ thread = threading.Thread(name=_CALLBACK_WORKER_NAME, target=worker)
+ thread.daemon = True
+ thread.start()
+ _LOGGER.debug("Started helper thread %s", thread.name)
+ self._thread = thread
+
+ def stop(self) -> None:
+ with self._operational_lock:
+ if self._thread is not None:
+ # Signal the worker to stop by queueing a "poison pill"
+ self._queue.put(helper_threads.STOP)
+ self._thread.join()
+
+ self._thread = None
+
+ def dispatch_callback(self, items: Sequence[RequestItem]) -> None:
+ """Map the callback request to the appropriate gRPC request.
+
+ Args:
+ items:
+ Queued requests to dispatch.
+ """
+ lease_requests: List[requests.LeaseRequest] = []
+ modack_requests: List[requests.ModAckRequest] = []
+ ack_requests: List[requests.AckRequest] = []
+ nack_requests: List[requests.NackRequest] = []
+ drop_requests: List[requests.DropRequest] = []
+
+ lease_ids = set()
+ modack_ids = set()
+ ack_ids = set()
+ nack_ids = set()
+ drop_ids = set()
+ exactly_once_delivery_enabled = self._manager._exactly_once_delivery_enabled()
+
+ for item in items:
+ if isinstance(item, requests.LeaseRequest):
+ if (
+ item.ack_id not in lease_ids
+ ): # LeaseRequests have no futures to handle.
+ lease_ids.add(item.ack_id)
+ lease_requests.append(item)
+ elif isinstance(item, requests.ModAckRequest):
+ if item.ack_id in modack_ids:
+ self._handle_duplicate_request_future(
+ exactly_once_delivery_enabled, item
+ )
+ else:
+ modack_ids.add(item.ack_id)
+ modack_requests.append(item)
+ elif isinstance(item, requests.AckRequest):
+ if item.ack_id in ack_ids:
+ self._handle_duplicate_request_future(
+ exactly_once_delivery_enabled, item
+ )
+ else:
+ ack_ids.add(item.ack_id)
+ ack_requests.append(item)
+ elif isinstance(item, requests.NackRequest):
+ if item.ack_id in nack_ids:
+ self._handle_duplicate_request_future(
+ exactly_once_delivery_enabled, item
+ )
+ else:
+ nack_ids.add(item.ack_id)
+ nack_requests.append(item)
+ elif isinstance(item, requests.DropRequest):
+ if (
+ item.ack_id not in drop_ids
+ ): # DropRequests have no futures to handle.
+ drop_ids.add(item.ack_id)
+ drop_requests.append(item)
+ else:
+ warnings.warn(
+ f'Skipping unknown request item of type "{type(item)}"',
+ category=RuntimeWarning,
+ )
+
+ _LOGGER.debug("Handling %d batched requests", len(items))
+
+ if lease_requests:
+ self.lease(lease_requests)
+
+ if modack_requests:
+ self.modify_ack_deadline(modack_requests)
+
+ # Note: Drop and ack *must* be after lease. It's possible to get both
+ # the lease and the ack/drop request in the same batch.
+ if ack_requests:
+ self.ack(ack_requests)
+
+ if nack_requests:
+ self.nack(nack_requests)
+
+ if drop_requests:
+ self.drop(drop_requests)
+
+ def _handle_duplicate_request_future(
+ self,
+ exactly_once_delivery_enabled: bool,
+ item: Union[requests.AckRequest, requests.ModAckRequest, requests.NackRequest],
+ ) -> None:
+ _LOGGER.debug(
+ "This is a duplicate %s with the same ack_id: %s.",
+ type(item),
+ item.ack_id,
+ )
+ if item.future:
+ if exactly_once_delivery_enabled:
+ item.future.set_exception(
+ ValueError(f"Duplicate ack_id for {type(item)}")
+ )
+ # Futures may be present even with exactly-once delivery
+ # disabled, in transition periods after the setting is changed on
+ # the subscription.
+ else:
+ # When exactly-once delivery is NOT enabled, acks/modacks are considered
+ # best-effort, so the future should succeed even though this is a duplicate.
+ item.future.set_result(AcknowledgeStatus.SUCCESS)
+
+ def ack(self, items: Sequence[requests.AckRequest]) -> None:
+ """Acknowledge the given messages.
+
+ Args:
+ items: The items to acknowledge.
+ """
+ # If we got timing information, add it to the histogram.
+ for item in items:
+ time_to_ack = item.time_to_ack
+ if time_to_ack is not None:
+ self._manager.ack_histogram.add(time_to_ack)
+
+ # We must potentially split the request into multiple smaller requests
+ # to avoid the server-side max request size limit.
+ items_gen = iter(items)
+ ack_ids_gen = (item.ack_id for item in items)
+ total_chunks = int(math.ceil(len(items) / _ACK_IDS_BATCH_SIZE))
+
+ for _ in range(total_chunks):
+ ack_reqs_dict = {
+ req.ack_id: req
+ for req in itertools.islice(items_gen, _ACK_IDS_BATCH_SIZE)
+ }
+ requests_completed, requests_to_retry = self._manager.send_unary_ack(
+ ack_ids=list(itertools.islice(ack_ids_gen, _ACK_IDS_BATCH_SIZE)),
+ ack_reqs_dict=ack_reqs_dict,
+ )
+
+ # Remove the completed messages from lease management.
+ self.drop(requests_completed)
+
+ # Retry on a separate thread so the dispatcher thread isn't blocked
+ # by sleeps.
+ if requests_to_retry:
+ self._start_retry_thread(
+ "Thread-RetryAcks",
+ functools.partial(self._retry_acks, requests_to_retry),
+ )
+
+ def _start_retry_thread(self, thread_name, thread_target):
+ # note: if the thread is *not* a daemon, a memory leak exists due to a cpython issue.
+ # https://github.com/googleapis/python-pubsub/issues/395#issuecomment-829910303
+ # https://github.com/googleapis/python-pubsub/issues/395#issuecomment-830092418
+ retry_thread = threading.Thread(
+ name=thread_name,
+ target=thread_target,
+ daemon=True,
+ )
+ # The thread finishes when the requests succeed or eventually fail with
+ # a back-end timeout error or other permanent failure.
+ retry_thread.start()
+
+ def _retry_acks(self, requests_to_retry):
+ retry_delay_gen = exponential_sleep_generator(
+ initial=_MIN_EXACTLY_ONCE_DELIVERY_ACK_MODACK_RETRY_DURATION_SECS,
+ maximum=_MAX_EXACTLY_ONCE_DELIVERY_ACK_MODACK_RETRY_DURATION_SECS,
+ )
+ while requests_to_retry:
+ time_to_wait = next(retry_delay_gen)
+ _LOGGER.debug(
+ "Retrying {len(requests_to_retry)} ack(s) after delay of "
+ + str(time_to_wait)
+ + " seconds"
+ )
+ time.sleep(time_to_wait)
+
+ ack_reqs_dict = {req.ack_id: req for req in requests_to_retry}
+ requests_completed, requests_to_retry = self._manager.send_unary_ack(
+ ack_ids=[req.ack_id for req in requests_to_retry],
+ ack_reqs_dict=ack_reqs_dict,
+ )
+ assert (
+ len(requests_to_retry) <= _ACK_IDS_BATCH_SIZE
+ ), "Too many requests to be retried."
+ # Remove the completed messages from lease management.
+ self.drop(requests_completed)
+
+ def drop(
+ self,
+ items: Sequence[
+ Union[requests.AckRequest, requests.DropRequest, requests.NackRequest]
+ ],
+ ) -> None:
+ """Remove the given messages from lease management.
+
+ Args:
+ items: The items to drop.
+ """
+ assert self._manager.leaser is not None
+ self._manager.leaser.remove(items)
+ ordering_keys = (k.ordering_key for k in items if k.ordering_key)
+ self._manager.activate_ordering_keys(ordering_keys)
+ self._manager.maybe_resume_consumer()
+
+ def lease(self, items: Sequence[requests.LeaseRequest]) -> None:
+ """Add the given messages to lease management.
+
+ Args:
+ items: The items to lease.
+ """
+ assert self._manager.leaser is not None
+ self._manager.leaser.add(items)
+ self._manager.maybe_pause_consumer()
+
+ def modify_ack_deadline(self, items: Sequence[requests.ModAckRequest]) -> None:
+ """Modify the ack deadline for the given messages.
+
+ Args:
+ items: The items to modify.
+ """
+ # We must potentially split the request into multiple smaller requests
+ # to avoid the server-side max request size limit.
+ items_gen = iter(items)
+ ack_ids_gen = (item.ack_id for item in items)
+ deadline_seconds_gen = (item.seconds for item in items)
+ total_chunks = int(math.ceil(len(items) / _ACK_IDS_BATCH_SIZE))
+
+ for _ in range(total_chunks):
+ ack_reqs_dict = {
+ req.ack_id: req
+ for req in itertools.islice(items_gen, _ACK_IDS_BATCH_SIZE)
+ }
+ # no further work needs to be done for `requests_to_retry`
+ requests_completed, requests_to_retry = self._manager.send_unary_modack(
+ modify_deadline_ack_ids=list(
+ itertools.islice(ack_ids_gen, _ACK_IDS_BATCH_SIZE)
+ ),
+ modify_deadline_seconds=list(
+ itertools.islice(deadline_seconds_gen, _ACK_IDS_BATCH_SIZE)
+ ),
+ ack_reqs_dict=ack_reqs_dict,
+ )
+ assert (
+ len(requests_to_retry) <= _ACK_IDS_BATCH_SIZE
+ ), "Too many requests to be retried."
+
+ # Retry on a separate thread so the dispatcher thread isn't blocked
+ # by sleeps.
+ if requests_to_retry:
+ self._start_retry_thread(
+ "Thread-RetryModAcks",
+ functools.partial(self._retry_modacks, requests_to_retry),
+ )
+
+ def _retry_modacks(self, requests_to_retry):
+ retry_delay_gen = exponential_sleep_generator(
+ initial=_MIN_EXACTLY_ONCE_DELIVERY_ACK_MODACK_RETRY_DURATION_SECS,
+ maximum=_MAX_EXACTLY_ONCE_DELIVERY_ACK_MODACK_RETRY_DURATION_SECS,
+ )
+ while requests_to_retry:
+ time_to_wait = next(retry_delay_gen)
+ _LOGGER.debug(
+ "Retrying {len(requests_to_retry)} modack(s) after delay of "
+ + str(time_to_wait)
+ + " seconds"
+ )
+ time.sleep(time_to_wait)
+
+ ack_reqs_dict = {req.ack_id: req for req in requests_to_retry}
+ requests_completed, requests_to_retry = self._manager.send_unary_modack(
+ modify_deadline_ack_ids=[req.ack_id for req in requests_to_retry],
+ modify_deadline_seconds=[req.seconds for req in requests_to_retry],
+ ack_reqs_dict=ack_reqs_dict,
+ )
+
+ def nack(self, items: Sequence[requests.NackRequest]) -> None:
+ """Explicitly deny receipt of messages.
+
+ Args:
+ items: The items to deny.
+ """
+ self.modify_ack_deadline(
+ [
+ requests.ModAckRequest(
+ ack_id=item.ack_id, seconds=0, future=item.future
+ )
+ for item in items
+ ]
+ )
+ self.drop(
+ [
+ requests.DropRequest(
+ ack_id=item.ack_id,
+ byte_size=item.byte_size,
+ ordering_key=item.ordering_key,
+ )
+ for item in items
+ ]
+ )
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/heartbeater.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/heartbeater.py
new file mode 100644
index 000000000000..a053d5fe4e08
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/heartbeater.py
@@ -0,0 +1,77 @@
+# Copyright 2018, Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import logging
+import threading
+import typing
+from typing import Optional
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1.subscriber._protocol.streaming_pull_manager import (
+ StreamingPullManager,
+ )
+
+
+_LOGGER = logging.getLogger(__name__)
+_HEARTBEAT_WORKER_NAME = "Thread-Heartbeater"
+# How often to send heartbeats in seconds. Determined as half the period of
+# time where the Pub/Sub server will close the stream as inactive, which is
+# 60 seconds.
+_DEFAULT_PERIOD = 30
+
+
+class Heartbeater(object):
+ def __init__(self, manager: "StreamingPullManager", period: int = _DEFAULT_PERIOD):
+ self._thread: Optional[threading.Thread] = None
+ self._operational_lock = threading.Lock()
+ self._manager = manager
+ self._stop_event = threading.Event()
+ self._period = period
+
+ def heartbeat(self) -> None:
+ """Periodically send streaming pull heartbeats."""
+ while not self._stop_event.is_set():
+ if self._manager.heartbeat():
+ _LOGGER.debug("Sent heartbeat.")
+ self._stop_event.wait(timeout=self._period)
+
+ _LOGGER.debug("%s exiting.", _HEARTBEAT_WORKER_NAME)
+
+ def start(self) -> None:
+ with self._operational_lock:
+ if self._thread is not None:
+ raise ValueError("Heartbeater is already running.")
+
+ # Create and start the helper thread.
+ self._stop_event.clear()
+ thread = threading.Thread(
+ name=_HEARTBEAT_WORKER_NAME, target=self.heartbeat
+ )
+ thread.daemon = True
+ thread.start()
+ _LOGGER.debug("Started helper thread %s", thread.name)
+ self._thread = thread
+
+ def stop(self) -> None:
+ with self._operational_lock:
+ self._stop_event.set()
+
+ if self._thread is not None:
+ # The thread should automatically exit when the consumer is
+ # inactive.
+ self._thread.join()
+
+ self._thread = None
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/helper_threads.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/helper_threads.py
new file mode 100644
index 000000000000..fbcab781df84
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/helper_threads.py
@@ -0,0 +1,122 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import queue
+import time
+from typing import Any, Callable, List, Sequence
+import uuid
+
+
+__all__ = ("QueueCallbackWorker", "STOP")
+
+_LOGGER = logging.getLogger(__name__)
+
+
+# Helper thread stop indicator. This could be a sentinel object or None,
+# but the sentinel object's ID can change if the process is forked, and
+# None has the possibility of a user accidentally killing the helper
+# thread.
+STOP = uuid.uuid4()
+
+
+def _get_many(
+ queue_: queue.Queue, max_items: int = None, max_latency: float = 0
+) -> List[Any]:
+ """Get multiple items from a Queue.
+
+ Gets at least one (blocking) and at most ``max_items`` items
+ (non-blocking) from a given Queue. Does not mark the items as done.
+
+ Args:
+ queue_: The Queue to get items from.
+ max_items:
+ The maximum number of items to get. If ``None``, then all available items
+ in the queue are returned.
+ max_latency:
+ The maximum number of seconds to wait for more than one item from a queue.
+ This number includes the time required to retrieve the first item.
+
+ Returns:
+ A sequence of items retrieved from the queue.
+ """
+ start = time.time()
+ # Always return at least one item.
+ items = [queue_.get()]
+ while max_items is None or len(items) < max_items:
+ try:
+ elapsed = time.time() - start
+ timeout = max(0, max_latency - elapsed)
+ items.append(queue_.get(timeout=timeout))
+ except queue.Empty:
+ break
+ return items
+
+
+class QueueCallbackWorker(object):
+ """A helper that executes a callback for items sent in a queue.
+
+ Calls a blocking ``get()`` on the ``queue`` until it encounters
+ :attr:`STOP`.
+
+ Args:
+ queue:
+ A Queue instance, appropriate for crossing the concurrency boundary
+ implemented by ``executor``. Items will be popped off (with a blocking
+ ``get()``) until :attr:`STOP` is encountered.
+ callback:
+ A callback that can process items pulled off of the queue. Multiple items
+ will be passed to the callback in batches.
+ max_items:
+ The maximum amount of items that will be passed to the callback at a time.
+ max_latency:
+ The maximum amount of time in seconds to wait for additional items before
+ executing the callback.
+ """
+
+ def __init__(
+ self,
+ queue: queue.Queue,
+ callback: Callable[[Sequence[Any]], Any],
+ max_items: int = 100,
+ max_latency: float = 0,
+ ):
+ self.queue = queue
+ self._callback = callback
+ self.max_items = max_items
+ self.max_latency = max_latency
+
+ def __call__(self) -> None:
+ continue_ = True
+ while continue_:
+ items = _get_many(
+ self.queue, max_items=self.max_items, max_latency=self.max_latency
+ )
+
+ # If stop is in the items, process all items up to STOP and then
+ # exit.
+ try:
+ items = items[: items.index(STOP)]
+ continue_ = False
+ except ValueError:
+ pass
+
+ # Run the callback. If any exceptions occur, log them and
+ # continue.
+ try:
+ self._callback(items)
+ except Exception as exc:
+ _LOGGER.exception("Error in queue callback worker: %s", exc)
+
+ _LOGGER.debug("Exiting the QueueCallbackWorker.")
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/histogram.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/histogram.py
new file mode 100644
index 000000000000..d922bbf685c7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/histogram.py
@@ -0,0 +1,159 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Dict, Optional, Union
+
+
+MIN_ACK_DEADLINE = 10
+MAX_ACK_DEADLINE = 600
+
+
+class Histogram(object):
+ """Representation of a single histogram.
+
+ The purpose of this class is to store actual ack timing information
+ in order to predict how long to renew leases.
+
+ The default implementation uses the 99th percentile of previous ack
+ times to implicitly lease messages; however, custom
+ :class:`~.pubsub_v1.subscriber._consumer.Consumer` subclasses
+ are free to use a different formula.
+
+ The precision of data stored is to the nearest integer. Additionally,
+ values outside the range of ``MIN_ACK_DEADLINE <= x <= MAX_ACK_DEADLINE`` are stored
+ as ``MIN_ACK_DEADLINE`` or ``MAX_ACK_DEADLINE``, since these are the boundaries of
+ leases in the actual API.
+ """
+
+ def __init__(self, data: Optional[Dict[int, int]] = None):
+ """Instantiate the histogram.
+
+ Args:
+ data:
+ The data strucure to be used to store the underlying data. The default
+ is an empty dictionary. This can be set to a dictionary-like object if
+ required (for example, if a special object is needed for concurrency
+ reasons).
+ """
+ # The data is stored as a dictionary, with the keys being the
+ # value being added and the values being the number of times that
+ # value was added to the dictionary.
+ #
+ # This is depending on the Python interpreter's implicit ordering
+ # of dictionaries, which is a bitwise sort by the key's ``hash()``
+ # value. Because ``hash(int i) -> i`` and all of our keys are
+ # positive integers (negatives would be a problem because the sort
+ # is bitwise), we can rely on this.
+ if data is None:
+ data = {}
+ self._data = data
+ self._len = 0
+
+ def __len__(self) -> int:
+ """Return the total number of data points in this histogram.
+
+ This is cached on a separate counter (rather than computing it using
+ ``sum([v for v in self._data.values()])``) to optimize lookup.
+
+ Returns:
+ The total number of data points in this histogram.
+ """
+ return self._len
+
+ def __contains__(self, needle: int) -> bool:
+ """Return ``True`` if needle is present in the histogram, ``False`` otherwise."""
+ return needle in self._data
+
+ def __repr__(self):
+ return "".format(
+ len=len(self), max=self.max, min=self.min
+ )
+
+ @property
+ def max(self) -> int:
+ """Return the maximum value in this histogram.
+
+ If there are no values in the histogram at all, return ``MAX_ACK_DEADLINE``.
+
+ Returns:
+ The maximum value in the histogram.
+ """
+ if len(self._data) == 0:
+ return MAX_ACK_DEADLINE
+ return next(iter(reversed(sorted(self._data.keys()))))
+
+ @property
+ def min(self) -> int:
+ """Return the minimum value in this histogram.
+
+ If there are no values in the histogram at all, return ``MIN_ACK_DEADLINE``.
+
+ Returns:
+ The minimum value in the histogram.
+ """
+ if len(self._data) == 0:
+ return MIN_ACK_DEADLINE
+ return next(iter(sorted(self._data.keys())))
+
+ def add(self, value: Union[int, float]) -> None:
+ """Add the value to this histogram.
+
+ Args:
+ value:
+ The value. Values outside of
+ ``MIN_ACK_DEADLINE <= x <= MAX_ACK_DEADLINE``
+ will be raised to ``MIN_ACK_DEADLINE`` or reduced to
+ ``MAX_ACK_DEADLINE``.
+ """
+ # If the value is out of bounds, bring it in bounds.
+ value = int(value)
+ if value < MIN_ACK_DEADLINE:
+ value = MIN_ACK_DEADLINE
+ elif value > MAX_ACK_DEADLINE:
+ value = MAX_ACK_DEADLINE
+
+ # Add the value to the histogram's data dictionary.
+ self._data.setdefault(value, 0)
+ self._data[value] += 1
+ self._len += 1
+
+ def percentile(self, percent: Union[int, float]) -> int:
+ """Return the value that is the Nth precentile in the histogram.
+
+ Args:
+ percent:
+ The precentile being sought. The default consumer implementations
+ consistently use ``99``.
+
+ Returns:
+ The value corresponding to the requested percentile.
+ """
+ # Sanity check: Any value over 100 should become 100.
+ if percent >= 100:
+ percent = 100
+
+ # Determine the actual target number.
+ target = len(self) - len(self) * (percent / 100)
+
+ # Iterate over the values in reverse, dropping the target by the
+ # number of times each value has been seen. When the target passes
+ # 0, return the value we are currently viewing.
+ for k in reversed(sorted(self._data.keys())):
+ target -= self._data[k]
+ if target < 0:
+ return k
+
+ # The only way to get here is if there was no data.
+ # In this case, just return the shortest possible deadline.
+ return MIN_ACK_DEADLINE
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/leaser.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/leaser.py
new file mode 100644
index 000000000000..508f4d7cefcb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/leaser.py
@@ -0,0 +1,241 @@
+# Copyright 2017, Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import copy
+import logging
+import random
+import threading
+import time
+import typing
+from typing import Dict, Iterable, Optional, Union
+
+from google.cloud.pubsub_v1.subscriber._protocol.dispatcher import _MAX_BATCH_LATENCY
+
+try:
+ from collections.abc import KeysView
+
+ KeysView[None] # KeysView is only subscriptable in Python 3.9+
+except TypeError:
+ # Deprecated since Python 3.9, thus only use as a fallback in older Python versions
+ from typing import KeysView
+
+from google.cloud.pubsub_v1.subscriber._protocol import requests
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1.subscriber._protocol.streaming_pull_manager import (
+ StreamingPullManager,
+ )
+
+
+_LOGGER = logging.getLogger(__name__)
+_LEASE_WORKER_NAME = "Thread-LeaseMaintainer"
+
+
+class _LeasedMessage(typing.NamedTuple):
+ sent_time: float
+ """The local time when ACK ID was initially leased in seconds since the epoch."""
+
+ size: int
+ ordering_key: Optional[str]
+
+
+class Leaser(object):
+ def __init__(self, manager: "StreamingPullManager"):
+ self._thread: Optional[threading.Thread] = None
+ self._manager = manager
+
+ # a lock used for start/stop operations, protecting the _thread attribute
+ self._operational_lock = threading.Lock()
+
+ # A lock ensuring that add/remove operations are atomic and cannot be
+ # intertwined. Protects the _leased_messages and _bytes attributes.
+ self._add_remove_lock = threading.Lock()
+
+ # Dict of ack_id -> _LeasedMessage
+ self._leased_messages: Dict[str, _LeasedMessage] = {}
+
+ self._bytes = 0
+ """The total number of bytes consumed by leased messages."""
+
+ self._stop_event = threading.Event()
+
+ @property
+ def message_count(self) -> int:
+ """The number of leased messages."""
+ return len(self._leased_messages)
+
+ @property
+ def ack_ids(self) -> KeysView[str]:
+ """The ack IDs of all leased messages."""
+ return self._leased_messages.keys()
+
+ @property
+ def bytes(self) -> int:
+ """The total size, in bytes, of all leased messages."""
+ return self._bytes
+
+ def add(self, items: Iterable[requests.LeaseRequest]) -> None:
+ """Add messages to be managed by the leaser."""
+ with self._add_remove_lock:
+ for item in items:
+ # Add the ack ID to the set of managed ack IDs, and increment
+ # the size counter.
+ if item.ack_id not in self._leased_messages:
+ self._leased_messages[item.ack_id] = _LeasedMessage(
+ sent_time=float("inf"),
+ size=item.byte_size,
+ ordering_key=item.ordering_key,
+ )
+ self._bytes += item.byte_size
+ else:
+ _LOGGER.debug("Message %s is already lease managed", item.ack_id)
+
+ def start_lease_expiry_timer(self, ack_ids: Iterable[str]) -> None:
+ """Start the lease expiry timer for `items`.
+
+ Args:
+ items: Sequence of ack-ids for which to start lease expiry timers.
+ """
+ with self._add_remove_lock:
+ for ack_id in ack_ids:
+ lease_info = self._leased_messages.get(ack_id)
+ # Lease info might not exist for this ack_id because it has already
+ # been removed by remove().
+ if lease_info:
+ self._leased_messages[ack_id] = lease_info._replace(
+ sent_time=time.time()
+ )
+
+ def remove(
+ self,
+ items: Iterable[
+ Union[requests.AckRequest, requests.DropRequest, requests.NackRequest]
+ ],
+ ) -> None:
+ """Remove messages from lease management."""
+ with self._add_remove_lock:
+ # Remove the ack ID from lease management, and decrement the
+ # byte counter.
+ for item in items:
+ if self._leased_messages.pop(item.ack_id, None) is not None:
+ self._bytes -= item.byte_size
+ else:
+ _LOGGER.debug("Item %s was not managed.", item.ack_id)
+
+ if self._bytes < 0:
+ _LOGGER.debug("Bytes was unexpectedly negative: %d", self._bytes)
+ self._bytes = 0
+
+ def maintain_leases(self) -> None:
+ """Maintain all of the leases being managed.
+
+ This method modifies the ack deadline for all of the managed
+ ack IDs, then waits for most of that time (but with jitter), and
+ repeats.
+ """
+ while not self._stop_event.is_set():
+ # Determine the appropriate duration for the lease. This is
+ # based off of how long previous messages have taken to ack, with
+ # a sensible default and within the ranges allowed by Pub/Sub.
+ # Also update the deadline currently used if enough new ACK data has been
+ # gathered since the last deadline update.
+ deadline = self._manager._obtain_ack_deadline(maybe_update=True)
+ _LOGGER.debug("The current deadline value is %d seconds.", deadline)
+
+ # Make a copy of the leased messages. This is needed because it's
+ # possible for another thread to modify the dictionary while
+ # we're iterating over it.
+ leased_messages = copy.copy(self._leased_messages)
+
+ # Drop any leases that are beyond the max lease time. This ensures
+ # that in the event of a badly behaving actor, we can drop messages
+ # and allow the Pub/Sub server to resend them.
+ cutoff = time.time() - self._manager.flow_control.max_lease_duration
+ to_drop = [
+ requests.DropRequest(ack_id, item.size, item.ordering_key)
+ for ack_id, item in leased_messages.items()
+ if item.sent_time < cutoff
+ ]
+
+ if to_drop:
+ _LOGGER.warning(
+ "Dropping %s items because they were leased too long.", len(to_drop)
+ )
+ assert self._manager.dispatcher is not None
+ self._manager.dispatcher.drop(to_drop)
+
+ # Remove dropped items from our copy of the leased messages (they
+ # have already been removed from the real one by
+ # self._manager.drop(), which calls self.remove()).
+ for item in to_drop:
+ leased_messages.pop(item.ack_id)
+
+ # Create a modack request.
+ # We do not actually call `modify_ack_deadline` over and over
+ # because it is more efficient to make a single request.
+ ack_ids = leased_messages.keys()
+ if ack_ids:
+ _LOGGER.debug("Renewing lease for %d ack IDs.", len(ack_ids))
+
+ # NOTE: This may not work as expected if ``consumer.active``
+ # has changed since we checked it. An implementation
+ # without any sort of race condition would require a
+ # way for ``send_request`` to fail when the consumer
+ # is inactive.
+ assert self._manager.dispatcher is not None
+ ack_id_gen = (ack_id for ack_id in ack_ids)
+ self._manager._send_lease_modacks(ack_id_gen, deadline)
+
+ # Now wait an appropriate period of time and do this again.
+ #
+ # We determine the appropriate period of time based on a random
+ # period between:
+ # minimum: MAX_BATCH_LATENCY (to prevent duplicate modacks being created in one batch)
+ # maximum: 90% of the deadline
+ # This maximum time attempts to prevent ack expiration before new lease modacks arrive at the server.
+ # This use of jitter (http://bit.ly/2s2ekL7) helps decrease contention in cases
+ # where there are many clients.
+ snooze = random.uniform(_MAX_BATCH_LATENCY, deadline * 0.9)
+ _LOGGER.debug("Snoozing lease management for %f seconds.", snooze)
+ self._stop_event.wait(timeout=snooze)
+
+ _LOGGER.debug("%s exiting.", _LEASE_WORKER_NAME)
+
+ def start(self) -> None:
+ with self._operational_lock:
+ if self._thread is not None:
+ raise ValueError("Leaser is already running.")
+
+ # Create and start the helper thread.
+ self._stop_event.clear()
+ thread = threading.Thread(
+ name=_LEASE_WORKER_NAME, target=self.maintain_leases
+ )
+ thread.daemon = True
+ thread.start()
+ _LOGGER.debug("Started helper thread %s", thread.name)
+ self._thread = thread
+
+ def stop(self) -> None:
+ with self._operational_lock:
+ self._stop_event.set()
+
+ if self._thread is not None:
+ # The thread should automatically exit when the consumer is
+ # inactive.
+ self._thread.join()
+
+ self._thread = None
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/messages_on_hold.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/messages_on_hold.py
new file mode 100644
index 000000000000..5c3cc1a75e8e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/messages_on_hold.py
@@ -0,0 +1,168 @@
+# Copyright 2020, Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import collections
+import typing
+from typing import Any, Callable, Iterable, Optional
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1 import subscriber
+
+
+class MessagesOnHold(object):
+ """Tracks messages on hold by ordering key. Not thread-safe."""
+
+ def __init__(self):
+ self._size = 0
+
+ # A FIFO queue for the messages that have been received from the server,
+ # but not yet sent to the user callback.
+ # Both ordered and unordered messages may be in this queue. Ordered
+ # message state tracked in _pending_ordered_messages once ordered
+ # messages are taken off this queue.
+ # The tail of the queue is to the right side of the deque; the head is
+ # to the left side.
+ self._messages_on_hold = collections.deque()
+
+ # Dict of ordering_key -> queue of ordered messages that have not been
+ # delivered to the user.
+ # All ordering keys in this collection have a message in flight. Once
+ # that one is acked or nacked, the next message in the queue for that
+ # ordering key will be sent.
+ # If the queue is empty, it means there's a message for that key in
+ # flight, but there are no pending messages.
+ self._pending_ordered_messages = {}
+
+ @property
+ def size(self) -> int:
+ """Return the number of messages on hold across ordered and unordered messages.
+
+ Note that this object may still store information about ordered messages
+ in flight even if size is zero.
+
+ Returns:
+ The size value.
+ """
+ return self._size
+
+ def get(self) -> Optional["subscriber.message.Message"]:
+ """Gets a message from the on-hold queue. A message with an ordering
+ key wont be returned if there's another message with the same key in
+ flight.
+
+ Returns:
+ A message that hasn't been sent to the user yet or ``None`` if there are no
+ messages available.
+ """
+ while self._messages_on_hold:
+ msg = self._messages_on_hold.popleft()
+
+ if msg.ordering_key:
+ pending_queue = self._pending_ordered_messages.get(msg.ordering_key)
+ if pending_queue is None:
+ # Create empty queue to indicate a message with the
+ # ordering key is in flight.
+ self._pending_ordered_messages[
+ msg.ordering_key
+ ] = collections.deque()
+ self._size = self._size - 1
+ return msg
+ else:
+ # Another message is in flight so add message to end of
+ # queue for this ordering key.
+ pending_queue.append(msg)
+ else:
+ # Unordered messages can be returned without any
+ # restrictions.
+ self._size = self._size - 1
+ return msg
+
+ return None
+
+ def put(self, message: "subscriber.message.Message") -> None:
+ """Put a message on hold.
+
+ Args:
+ message: The message to put on hold.
+ """
+ self._messages_on_hold.append(message)
+ self._size = self._size + 1
+
+ def activate_ordering_keys(
+ self,
+ ordering_keys: Iterable[str],
+ schedule_message_callback: Callable[["subscriber.message.Message"], Any],
+ ) -> None:
+ """Send the next message in the queue for each of the passed-in
+ ordering keys, if they exist. Clean up state for keys that no longer
+ have any queued messages.
+
+ See comment at streaming_pull_manager.activate_ordering_keys() for more
+ detail about the impact of this method on load.
+
+ Args:
+ ordering_keys:
+ The ordering keys to activate. May be empty.
+ schedule_message_callback:
+ The callback to call to schedule a message to be sent to the user.
+ """
+ for key in ordering_keys:
+ assert (
+ self._pending_ordered_messages.get(key) is not None
+ ), "A message queue should exist for every ordered message in flight."
+ next_msg = self._get_next_for_ordering_key(key)
+ if next_msg:
+ # Schedule the next message because the previous was dropped.
+ # Note that this may overload the user's `max_bytes` limit, but
+ # not their `max_messages` limit.
+ schedule_message_callback(next_msg)
+ else:
+ # No more messages for this ordering key, so do clean-up.
+ self._clean_up_ordering_key(key)
+
+ def _get_next_for_ordering_key(
+ self, ordering_key: str
+ ) -> Optional["subscriber.message.Message"]:
+ """Get next message for ordering key.
+
+ The client should call clean_up_ordering_key() if this method returns
+ None.
+
+ Args:
+ ordering_key: Ordering key for which to get the next message.
+
+ Returns:
+ The next message for this ordering key or None if there aren't any.
+ """
+ queue_for_key = self._pending_ordered_messages.get(ordering_key)
+ if queue_for_key:
+ self._size = self._size - 1
+ return queue_for_key.popleft()
+ return None
+
+ def _clean_up_ordering_key(self, ordering_key: str) -> None:
+ """Clean up state for an ordering key with no pending messages.
+
+ Args:
+ ordering_key: The ordering key to clean up.
+ """
+ message_queue = self._pending_ordered_messages.get(ordering_key)
+ assert (
+ message_queue is not None
+ ), "Cleaning up ordering key that does not exist."
+ assert not len(message_queue), (
+ "Ordering key must only be removed if there are no messages "
+ "left for that key."
+ )
+ del self._pending_ordered_messages[ordering_key]
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/requests.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/requests.py
new file mode 100644
index 000000000000..9cd387545909
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/requests.py
@@ -0,0 +1,54 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import typing
+from typing import NamedTuple, Optional
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1.subscriber import futures
+
+
+# Namedtuples for management requests. Used by the Message class to communicate
+# items of work back to the policy.
+class AckRequest(NamedTuple):
+ ack_id: str
+ byte_size: int
+ time_to_ack: float
+ ordering_key: Optional[str]
+ future: Optional["futures.Future"]
+
+
+class DropRequest(NamedTuple):
+ ack_id: str
+ byte_size: int
+ ordering_key: Optional[str]
+
+
+class LeaseRequest(NamedTuple):
+ ack_id: str
+ byte_size: int
+ ordering_key: Optional[str]
+
+
+class ModAckRequest(NamedTuple):
+ ack_id: str
+ seconds: float
+ future: Optional["futures.Future"]
+
+
+class NackRequest(NamedTuple):
+ ack_id: str
+ byte_size: int
+ ordering_key: Optional[str]
+ future: Optional["futures.Future"]
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/streaming_pull_manager.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/streaming_pull_manager.py
new file mode 100644
index 000000000000..89dc93e74ee8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/_protocol/streaming_pull_manager.py
@@ -0,0 +1,1179 @@
+# Copyright 2017, Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import division
+
+import collections
+import functools
+import itertools
+import logging
+import threading
+import typing
+from typing import Any, Dict, Callable, Iterable, List, Optional, Tuple
+import uuid
+
+import grpc # type: ignore
+
+from google.api_core import bidi
+from google.api_core import exceptions
+from google.cloud.pubsub_v1 import types
+from google.cloud.pubsub_v1.subscriber._protocol import dispatcher
+from google.cloud.pubsub_v1.subscriber._protocol import heartbeater
+from google.cloud.pubsub_v1.subscriber._protocol import histogram
+from google.cloud.pubsub_v1.subscriber._protocol import leaser
+from google.cloud.pubsub_v1.subscriber._protocol import messages_on_hold
+from google.cloud.pubsub_v1.subscriber._protocol import requests
+from google.cloud.pubsub_v1.subscriber.exceptions import (
+ AcknowledgeError,
+ AcknowledgeStatus,
+)
+import google.cloud.pubsub_v1.subscriber.message
+from google.cloud.pubsub_v1.subscriber import futures
+from google.cloud.pubsub_v1.subscriber.scheduler import ThreadScheduler
+from google.pubsub_v1 import types as gapic_types
+from grpc_status import rpc_status # type: ignore
+from google.rpc.error_details_pb2 import ErrorInfo # type: ignore
+from google.rpc import code_pb2 # type: ignore
+from google.rpc import status_pb2
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1 import subscriber
+
+
+_LOGGER = logging.getLogger(__name__)
+_REGULAR_SHUTDOWN_THREAD_NAME = "Thread-RegularStreamShutdown"
+_RPC_ERROR_THREAD_NAME = "Thread-OnRpcTerminated"
+_RETRYABLE_STREAM_ERRORS = (
+ exceptions.DeadlineExceeded,
+ exceptions.ServiceUnavailable,
+ exceptions.InternalServerError,
+ exceptions.Unknown,
+ exceptions.GatewayTimeout,
+ exceptions.Aborted,
+)
+_TERMINATING_STREAM_ERRORS = (exceptions.Cancelled,)
+_MAX_LOAD = 1.0
+"""The load threshold above which to pause the incoming message stream."""
+
+_RESUME_THRESHOLD = 0.8
+"""The load threshold below which to resume the incoming message stream."""
+
+_MIN_ACK_DEADLINE_SECS_WHEN_EXACTLY_ONCE_ENABLED = 60
+"""The minimum ack_deadline, in seconds, for when exactly_once is enabled for
+a subscription. We do this to reduce premature ack expiration.
+"""
+
+_DEFAULT_STREAM_ACK_DEADLINE: float = 60
+"""The default stream ack deadline in seconds."""
+
+_MAX_STREAM_ACK_DEADLINE: float = 600
+"""The maximum stream ack deadline in seconds."""
+
+_MIN_STREAM_ACK_DEADLINE: float = 10
+"""The minimum stream ack deadline in seconds."""
+
+_EXACTLY_ONCE_DELIVERY_TEMPORARY_RETRY_ERRORS = {
+ code_pb2.DEADLINE_EXCEEDED,
+ code_pb2.RESOURCE_EXHAUSTED,
+ code_pb2.ABORTED,
+ code_pb2.INTERNAL,
+ code_pb2.UNAVAILABLE,
+}
+
+
+def _wrap_as_exception(maybe_exception: Any) -> BaseException:
+ """Wrap an object as a Python exception, if needed.
+
+ Args:
+ maybe_exception: The object to wrap, usually a gRPC exception class.
+
+ Returns:
+ The argument itself if an instance of ``BaseException``, otherwise
+ the argument represented as an instance of ``Exception`` (sub)class.
+ """
+ if isinstance(maybe_exception, grpc.RpcError):
+ return exceptions.from_grpc_error(maybe_exception)
+ elif isinstance(maybe_exception, BaseException):
+ return maybe_exception
+
+ return Exception(maybe_exception)
+
+
+def _wrap_callback_errors(
+ callback: Callable[["google.cloud.pubsub_v1.subscriber.message.Message"], Any],
+ on_callback_error: Callable[[Exception], Any],
+ message: "google.cloud.pubsub_v1.subscriber.message.Message",
+):
+ """Wraps a user callback so that if an exception occurs the message is
+ nacked.
+
+ Args:
+ callback: The user callback.
+ message: The Pub/Sub message.
+ """
+ try:
+ callback(message)
+ except Exception as exc:
+ # Note: the likelihood of this failing is extremely low. This just adds
+ # a message to a queue, so if this doesn't work the world is in an
+ # unrecoverable state and this thread should just bail.
+ _LOGGER.exception(
+ "Top-level exception occurred in callback while processing a message"
+ )
+ message.nack()
+ on_callback_error(exc)
+
+
+def _get_status(
+ exc: exceptions.GoogleAPICallError,
+) -> Optional["status_pb2.Status"]:
+ if not exc.response:
+ _LOGGER.debug("No response obj in errored RPC call.")
+ return None
+ try:
+ return rpc_status.from_call(exc.response)
+ # Possible "If the gRPC call’s code or details are inconsistent
+ # with the status code and message inside of the
+ # google.rpc.status.Status"
+ except ValueError:
+ _LOGGER.debug("ValueError when parsing ErrorInfo.", exc_info=True)
+ return None
+
+
+def _get_ack_errors(
+ exc: exceptions.GoogleAPICallError,
+) -> Optional[Dict[str, str]]:
+ status = _get_status(exc)
+ if not status:
+ _LOGGER.debug("Unable to get status of errored RPC.")
+ return None
+ for detail in status.details:
+ info = ErrorInfo()
+ if not (detail.Is(ErrorInfo.DESCRIPTOR) and detail.Unpack(info)):
+ _LOGGER.debug("Unable to unpack ErrorInfo.")
+ return None
+ return info.metadata
+ return None
+
+
+def _process_requests(
+ error_status: Optional["status_pb2.Status"],
+ ack_reqs_dict: Dict[str, requests.AckRequest],
+ errors_dict: Optional[Dict[str, str]],
+):
+ """Process requests when exactly-once delivery is enabled by referring to
+ error_status and errors_dict.
+
+ The errors returned by the server in as `error_status` or in `errors_dict`
+ are used to complete the request futures in `ack_reqs_dict` (with a success
+ or exception) or to return requests for further retries.
+ """
+ requests_completed = []
+ requests_to_retry = []
+ for ack_id in ack_reqs_dict:
+ # Handle special errors returned for ack/modack RPCs via the ErrorInfo
+ # sidecar metadata when exactly-once delivery is enabled.
+ if errors_dict and ack_id in errors_dict:
+ exactly_once_error = errors_dict[ack_id]
+ if exactly_once_error.startswith("TRANSIENT_"):
+ requests_to_retry.append(ack_reqs_dict[ack_id])
+ else:
+ if exactly_once_error == "PERMANENT_FAILURE_INVALID_ACK_ID":
+ exc = AcknowledgeError(AcknowledgeStatus.INVALID_ACK_ID, info=None)
+ else:
+ exc = AcknowledgeError(AcknowledgeStatus.OTHER, exactly_once_error)
+ future = ack_reqs_dict[ack_id].future
+ if future is not None:
+ future.set_exception(exc)
+ requests_completed.append(ack_reqs_dict[ack_id])
+ # Temporary GRPC errors are retried
+ elif (
+ error_status
+ and error_status.code in _EXACTLY_ONCE_DELIVERY_TEMPORARY_RETRY_ERRORS
+ ):
+ requests_to_retry.append(ack_reqs_dict[ack_id])
+ # Other GRPC errors are NOT retried
+ elif error_status:
+ if error_status.code == code_pb2.PERMISSION_DENIED:
+ exc = AcknowledgeError(AcknowledgeStatus.PERMISSION_DENIED, info=None)
+ elif error_status.code == code_pb2.FAILED_PRECONDITION:
+ exc = AcknowledgeError(AcknowledgeStatus.FAILED_PRECONDITION, info=None)
+ else:
+ exc = AcknowledgeError(AcknowledgeStatus.OTHER, str(error_status))
+ future = ack_reqs_dict[ack_id].future
+ if future is not None:
+ future.set_exception(exc)
+ requests_completed.append(ack_reqs_dict[ack_id])
+ # Since no error occurred, requests with futures are completed successfully.
+ elif ack_reqs_dict[ack_id].future:
+ future = ack_reqs_dict[ack_id].future
+ # success
+ assert future is not None
+ future.set_result(AcknowledgeStatus.SUCCESS)
+ requests_completed.append(ack_reqs_dict[ack_id])
+ # All other requests are considered completed.
+ else:
+ requests_completed.append(ack_reqs_dict[ack_id])
+
+ return requests_completed, requests_to_retry
+
+
+class StreamingPullManager(object):
+ """The streaming pull manager coordinates pulling messages from Pub/Sub,
+ leasing them, and scheduling them to be processed.
+
+ Args:
+ client:
+ The subscriber client used to create this instance.
+ subscription:
+ The name of the subscription. The canonical format for this is
+ ``projects/{project}/subscriptions/{subscription}``.
+ flow_control:
+ The flow control settings.
+ scheduler:
+ The scheduler to use to process messages. If not provided, a thread
+ pool-based scheduler will be used.
+ use_legacy_flow_control:
+ If set to ``True``, flow control at the Cloud Pub/Sub server is disabled,
+ though client-side flow control is still enabled. If set to ``False``
+ (default), both server-side and client-side flow control are enabled.
+ await_callbacks_on_shutdown:
+ If ``True``, the shutdown thread will wait until all scheduler threads
+ terminate and only then proceed with shutting down the remaining running
+ helper threads.
+
+ If ``False`` (default), the shutdown thread will shut the scheduler down,
+ but it will not wait for the currently executing scheduler threads to
+ terminate.
+
+ This setting affects when the on close callbacks get invoked, and
+ consequently, when the StreamingPullFuture associated with the stream gets
+ resolved.
+ """
+
+ def __init__(
+ self,
+ client: "subscriber.Client",
+ subscription: str,
+ flow_control: types.FlowControl = types.FlowControl(),
+ scheduler: ThreadScheduler = None,
+ use_legacy_flow_control: bool = False,
+ await_callbacks_on_shutdown: bool = False,
+ ):
+ self._client = client
+ self._subscription = subscription
+ self._exactly_once_enabled = False
+ self._flow_control = flow_control
+ self._use_legacy_flow_control = use_legacy_flow_control
+ self._await_callbacks_on_shutdown = await_callbacks_on_shutdown
+ self._ack_histogram = histogram.Histogram()
+ self._last_histogram_size = 0
+
+ # If max_duration_per_lease_extension is the default
+ # we set the stream_ack_deadline to the default of 60
+ if self._flow_control.max_duration_per_lease_extension == 0:
+ self._stream_ack_deadline = _DEFAULT_STREAM_ACK_DEADLINE
+ # We will not be able to extend more than the default minimum
+ elif (
+ self._flow_control.max_duration_per_lease_extension
+ < _MIN_STREAM_ACK_DEADLINE
+ ):
+ self._stream_ack_deadline = _MIN_STREAM_ACK_DEADLINE
+ # Will not be able to extend past the max
+ elif (
+ self._flow_control.max_duration_per_lease_extension
+ > _MAX_STREAM_ACK_DEADLINE
+ ):
+ self._stream_ack_deadline = _MAX_STREAM_ACK_DEADLINE
+ else:
+ self._stream_ack_deadline = (
+ self._flow_control.max_duration_per_lease_extension
+ )
+
+ self._ack_deadline = max(
+ min(
+ self._flow_control.min_duration_per_lease_extension,
+ histogram.MAX_ACK_DEADLINE,
+ ),
+ histogram.MIN_ACK_DEADLINE,
+ )
+
+ self._rpc: Optional[bidi.ResumableBidiRpc] = None
+ self._callback: Optional[functools.partial] = None
+ self._closing = threading.Lock()
+ self._closed = False
+ self._close_callbacks: List[Callable[["StreamingPullManager", Any], Any]] = []
+ # Guarded by self._exactly_once_enabled_lock
+ self._send_new_ack_deadline = False
+
+ # A shutdown thread is created on intentional shutdown.
+ self._regular_shutdown_thread: Optional[threading.Thread] = None
+
+ # Generate a random client id tied to this object. All streaming pull
+ # connections (initial and re-connects) will then use the same client
+ # id. Doing so lets the server establish affinity even across stream
+ # disconncetions.
+ self._client_id = str(uuid.uuid4())
+
+ if scheduler is None:
+ self._scheduler: Optional[ThreadScheduler] = ThreadScheduler()
+ else:
+ self._scheduler = scheduler
+
+ # A collection for the messages that have been received from the server,
+ # but not yet sent to the user callback.
+ self._messages_on_hold = messages_on_hold.MessagesOnHold()
+
+ # The total number of bytes consumed by the messages currently on hold
+ self._on_hold_bytes = 0
+
+ # A lock ensuring that pausing / resuming the consumer are both atomic
+ # operations that cannot be executed concurrently. Needed for properly
+ # syncing these operations with the current leaser load. Additionally,
+ # the lock is used to protect modifications of internal data that
+ # affects the load computation, i.e. the count and size of the messages
+ # currently on hold.
+ self._pause_resume_lock = threading.Lock()
+
+ # A lock guarding the self._exactly_once_enabled variable. We may also
+ # acquire the self._ack_deadline_lock while this lock is held, but not
+ # the reverse. So, we maintain a simple ordering of these two locks to
+ # prevent deadlocks.
+ self._exactly_once_enabled_lock = threading.Lock()
+
+ # A lock protecting the current ACK deadline used in the lease management. This
+ # value can be potentially updated both by the leaser thread and by the message
+ # consumer thread when invoking the internal _on_response() callback.
+ self._ack_deadline_lock = threading.Lock()
+
+ # The threads created in ``.open()``.
+ self._dispatcher: Optional[dispatcher.Dispatcher] = None
+ self._leaser: Optional[leaser.Leaser] = None
+ self._consumer: Optional[bidi.BackgroundConsumer] = None
+ self._heartbeater: Optional[heartbeater.Heartbeater] = None
+
+ @property
+ def is_active(self) -> bool:
+ """``True`` if this manager is actively streaming.
+
+ Note that ``False`` does not indicate this is complete shut down,
+ just that it stopped getting new messages.
+ """
+ return self._consumer is not None and self._consumer.is_active
+
+ @property
+ def flow_control(self) -> types.FlowControl:
+ """The active flow control settings."""
+ return self._flow_control
+
+ @property
+ def dispatcher(self) -> Optional[dispatcher.Dispatcher]:
+ """The dispatcher helper."""
+ return self._dispatcher
+
+ @property
+ def leaser(self) -> Optional[leaser.Leaser]:
+ """The leaser helper."""
+ return self._leaser
+
+ @property
+ def ack_histogram(self) -> histogram.Histogram:
+ """The histogram tracking time-to-acknowledge."""
+ return self._ack_histogram
+
+ @property
+ def ack_deadline(self) -> float:
+ """Return the current ACK deadline based on historical data without updating it.
+
+ Returns:
+ The ack deadline.
+ """
+ return self._obtain_ack_deadline(maybe_update=False)
+
+ def _obtain_ack_deadline(self, maybe_update: bool) -> float:
+ """The actual `ack_deadline` implementation.
+
+ This method is "sticky". It will only perform the computations to check on the
+ right ACK deadline if explicitly requested AND if the histogram with past
+ time-to-ack data has gained a significant amount of new information.
+
+ Args:
+ maybe_update:
+ If ``True``, also update the current ACK deadline before returning it if
+ enough new ACK data has been gathered.
+
+ Returns:
+ The current ACK deadline in seconds to use.
+ """
+ with self._ack_deadline_lock:
+ if not maybe_update:
+ return self._ack_deadline
+
+ target_size = min(
+ self._last_histogram_size * 2, self._last_histogram_size + 100
+ )
+ hist_size = len(self.ack_histogram)
+
+ if hist_size > target_size:
+ self._last_histogram_size = hist_size
+ self._ack_deadline = self.ack_histogram.percentile(percent=99)
+
+ if self.flow_control.max_duration_per_lease_extension > 0:
+ # The setting in flow control could be too low, adjust if needed.
+ flow_control_setting = max(
+ self.flow_control.max_duration_per_lease_extension,
+ histogram.MIN_ACK_DEADLINE,
+ )
+ self._ack_deadline = min(self._ack_deadline, flow_control_setting)
+
+ # If the user explicitly sets a min ack_deadline, respect it.
+ if self.flow_control.min_duration_per_lease_extension > 0:
+ # The setting in flow control could be too high, adjust if needed.
+ flow_control_setting = min(
+ self.flow_control.min_duration_per_lease_extension,
+ histogram.MAX_ACK_DEADLINE,
+ )
+ self._ack_deadline = max(self._ack_deadline, flow_control_setting)
+ elif self._exactly_once_enabled:
+ # Higher minimum ack_deadline for subscriptions with
+ # exactly-once delivery enabled.
+ self._ack_deadline = max(
+ self._ack_deadline, _MIN_ACK_DEADLINE_SECS_WHEN_EXACTLY_ONCE_ENABLED
+ )
+ # If we have updated the ack_deadline and it is longer than the stream_ack_deadline
+ # set the stream_ack_deadline to the new ack_deadline.
+ if self._ack_deadline > self._stream_ack_deadline:
+ self._stream_ack_deadline = self._ack_deadline
+ return self._ack_deadline
+
+ @property
+ def load(self) -> float:
+ """Return the current load.
+
+ The load is represented as a float, where 1.0 represents having
+ hit one of the flow control limits, and values between 0.0 and 1.0
+ represent how close we are to them. (0.5 means we have exactly half
+ of what the flow control setting allows, for example.)
+
+ There are (currently) two flow control settings; this property
+ computes how close the manager is to each of them, and returns
+ whichever value is higher. (It does not matter that we have lots of
+ running room on setting A if setting B is over.)
+
+ Returns:
+ The load value.
+ """
+ if self._leaser is None:
+ return 0.0
+
+ # Messages that are temporarily put on hold are not being delivered to
+ # user's callbacks, thus they should not contribute to the flow control
+ # load calculation.
+ # However, since these messages must still be lease-managed to avoid
+ # unnecessary ACK deadline expirations, their count and total size must
+ # be subtracted from the leaser's values.
+ return max(
+ [
+ (self._leaser.message_count - self._messages_on_hold.size)
+ / self._flow_control.max_messages,
+ (self._leaser.bytes - self._on_hold_bytes)
+ / self._flow_control.max_bytes,
+ ]
+ )
+
+ def add_close_callback(
+ self, callback: Callable[["StreamingPullManager", Any], Any]
+ ) -> None:
+ """Schedules a callable when the manager closes.
+
+ Args:
+ The method to call.
+ """
+ self._close_callbacks.append(callback)
+
+ def activate_ordering_keys(self, ordering_keys: Iterable[str]) -> None:
+ """Send the next message in the queue for each of the passed-in
+ ordering keys, if they exist. Clean up state for keys that no longer
+ have any queued messages.
+
+ Since the load went down by one message, it's probably safe to send the
+ user another message for the same key. Since the released message may be
+ bigger than the previous one, this may increase the load above the maximum.
+ This decision is by design because it simplifies MessagesOnHold.
+
+ Args:
+ ordering_keys:
+ A sequence of ordering keys to activate. May be empty.
+ """
+ with self._pause_resume_lock:
+ if self._scheduler is None:
+ return # We are shutting down, don't try to dispatch any more messages.
+
+ self._messages_on_hold.activate_ordering_keys(
+ ordering_keys, self._schedule_message_on_hold
+ )
+
+ def maybe_pause_consumer(self) -> None:
+ """Check the current load and pause the consumer if needed."""
+ with self._pause_resume_lock:
+ if self.load >= _MAX_LOAD:
+ if self._consumer is not None and not self._consumer.is_paused:
+ _LOGGER.debug(
+ "Message backlog over load at %.2f, pausing.", self.load
+ )
+ self._consumer.pause()
+
+ def maybe_resume_consumer(self) -> None:
+ """Check the load and held messages and resume the consumer if needed.
+
+ If there are messages held internally, release those messages before
+ resuming the consumer. That will avoid leaser overload.
+ """
+ with self._pause_resume_lock:
+ # If we have been paused by flow control, check and see if we are
+ # back within our limits.
+ #
+ # In order to not thrash too much, require us to have passed below
+ # the resume threshold (80% by default) of each flow control setting
+ # before restarting.
+ if self._consumer is None or not self._consumer.is_paused:
+ return
+
+ _LOGGER.debug("Current load: %.2f", self.load)
+
+ # Before maybe resuming the background consumer, release any messages
+ # currently on hold, if the current load allows for it.
+ self._maybe_release_messages()
+
+ if self.load < _RESUME_THRESHOLD:
+ _LOGGER.debug("Current load is %.2f, resuming consumer.", self.load)
+ self._consumer.resume()
+ else:
+ _LOGGER.debug("Did not resume, current load is %.2f.", self.load)
+
+ def _maybe_release_messages(self) -> None:
+ """Release (some of) the held messages if the current load allows for it.
+
+ The method tries to release as many messages as the current leaser load
+ would allow. Each released message is added to the lease management,
+ and the user callback is scheduled for it.
+
+ If there are currently no messages on hold, or if the leaser is
+ already overloaded, this method is effectively a no-op.
+
+ The method assumes the caller has acquired the ``_pause_resume_lock``.
+ """
+ released_ack_ids = []
+ while self.load < _MAX_LOAD:
+ msg = self._messages_on_hold.get()
+ if not msg:
+ break
+
+ self._schedule_message_on_hold(msg)
+ released_ack_ids.append(msg.ack_id)
+
+ assert self._leaser is not None
+ self._leaser.start_lease_expiry_timer(released_ack_ids)
+
+ def _schedule_message_on_hold(
+ self, msg: "google.cloud.pubsub_v1.subscriber.message.Message"
+ ):
+ """Schedule a message on hold to be sent to the user and change on-hold-bytes.
+
+ The method assumes the caller has acquired the ``_pause_resume_lock``.
+
+ Args:
+ msg: The message to schedule to be sent to the user.
+ """
+ assert msg, "Message must not be None."
+
+ # On-hold bytes goes down, increasing load.
+ self._on_hold_bytes -= msg.size
+
+ if self._on_hold_bytes < 0:
+ _LOGGER.warning(
+ "On hold bytes was unexpectedly negative: %s", self._on_hold_bytes
+ )
+ self._on_hold_bytes = 0
+
+ _LOGGER.debug(
+ "Released held message, scheduling callback for it, "
+ "still on hold %s (bytes %s).",
+ self._messages_on_hold.size,
+ self._on_hold_bytes,
+ )
+ assert self._scheduler is not None
+ assert self._callback is not None
+ self._scheduler.schedule(self._callback, msg)
+
+ def send_unary_ack(
+ self, ack_ids, ack_reqs_dict
+ ) -> Tuple[List[requests.AckRequest], List[requests.AckRequest]]:
+ """Send a request using a separate unary request instead of over the stream.
+
+ If a RetryError occurs, the manager shutdown is triggered, and the
+ error is re-raised.
+ """
+ assert ack_ids
+ assert len(ack_ids) == len(ack_reqs_dict)
+
+ error_status = None
+ ack_errors_dict = None
+ try:
+ self._client.acknowledge(subscription=self._subscription, ack_ids=ack_ids)
+ except exceptions.GoogleAPICallError as exc:
+ _LOGGER.debug(
+ "Exception while sending unary RPC. This is typically "
+ "non-fatal as stream requests are best-effort.",
+ exc_info=True,
+ )
+ error_status = _get_status(exc)
+ ack_errors_dict = _get_ack_errors(exc)
+ except exceptions.RetryError as exc:
+ exactly_once_delivery_enabled = self._exactly_once_delivery_enabled()
+ # Makes sure to complete futures so they don't block forever.
+ for req in ack_reqs_dict.values():
+ # Futures may be present even with exactly-once delivery
+ # disabled, in transition periods after the setting is changed on
+ # the subscription.
+ if req.future:
+ if exactly_once_delivery_enabled:
+ e = AcknowledgeError(
+ AcknowledgeStatus.OTHER, "RetryError while sending ack RPC."
+ )
+ req.future.set_exception(e)
+ else:
+ req.future.set_result(AcknowledgeStatus.SUCCESS)
+
+ _LOGGER.debug(
+ "RetryError while sending ack RPC. Waiting on a transient "
+ "error resolution for too long, will now trigger shutdown.",
+ exc_info=False,
+ )
+ # The underlying channel has been suffering from a retryable error
+ # for too long, time to give up and shut the streaming pull down.
+ self._on_rpc_done(exc)
+ raise
+
+ if self._exactly_once_delivery_enabled():
+ requests_completed, requests_to_retry = _process_requests(
+ error_status, ack_reqs_dict, ack_errors_dict
+ )
+ else:
+ requests_completed = []
+ requests_to_retry = []
+ # When exactly-once delivery is NOT enabled, acks/modacks are considered
+ # best-effort. So, they always succeed even if the RPC fails.
+ for req in ack_reqs_dict.values():
+ # Futures may be present even with exactly-once delivery
+ # disabled, in transition periods after the setting is changed on
+ # the subscription.
+ if req.future:
+ req.future.set_result(AcknowledgeStatus.SUCCESS)
+ requests_completed.append(req)
+
+ return requests_completed, requests_to_retry
+
+ def send_unary_modack(
+ self, modify_deadline_ack_ids, modify_deadline_seconds, ack_reqs_dict
+ ) -> Tuple[List[requests.ModAckRequest], List[requests.ModAckRequest]]:
+ """Send a request using a separate unary request instead of over the stream.
+
+ If a RetryError occurs, the manager shutdown is triggered, and the
+ error is re-raised.
+ """
+ assert modify_deadline_ack_ids
+
+ error_status = None
+ modack_errors_dict = None
+ try:
+ # Send ack_ids with the same deadline seconds together.
+ deadline_to_ack_ids = collections.defaultdict(list)
+
+ for n, ack_id in enumerate(modify_deadline_ack_ids):
+ deadline = modify_deadline_seconds[n]
+ deadline_to_ack_ids[deadline].append(ack_id)
+
+ for deadline, ack_ids in deadline_to_ack_ids.items():
+ self._client.modify_ack_deadline(
+ subscription=self._subscription,
+ ack_ids=ack_ids,
+ ack_deadline_seconds=deadline,
+ )
+ except exceptions.GoogleAPICallError as exc:
+ _LOGGER.debug(
+ "Exception while sending unary RPC. This is typically "
+ "non-fatal as stream requests are best-effort.",
+ exc_info=True,
+ )
+ error_status = _get_status(exc)
+ modack_errors_dict = _get_ack_errors(exc)
+ except exceptions.RetryError as exc:
+ exactly_once_delivery_enabled = self._exactly_once_delivery_enabled()
+ # Makes sure to complete futures so they don't block forever.
+ for req in ack_reqs_dict.values():
+ # Futures may be present even with exactly-once delivery
+ # disabled, in transition periods after the setting is changed on
+ # the subscription.
+ if req.future:
+ if exactly_once_delivery_enabled:
+ e = AcknowledgeError(
+ AcknowledgeStatus.OTHER,
+ "RetryError while sending modack RPC.",
+ )
+ req.future.set_exception(e)
+ else:
+ req.future.set_result(AcknowledgeStatus.SUCCESS)
+
+ _LOGGER.debug(
+ "RetryError while sending modack RPC. Waiting on a transient "
+ "error resolution for too long, will now trigger shutdown.",
+ exc_info=False,
+ )
+ # The underlying channel has been suffering from a retryable error
+ # for too long, time to give up and shut the streaming pull down.
+ self._on_rpc_done(exc)
+ raise
+
+ if self._exactly_once_delivery_enabled():
+ requests_completed, requests_to_retry = _process_requests(
+ error_status, ack_reqs_dict, modack_errors_dict
+ )
+ else:
+ requests_completed = []
+ requests_to_retry = []
+ # When exactly-once delivery is NOT enabled, acks/modacks are considered
+ # best-effort. So, they always succeed even if the RPC fails.
+ for req in ack_reqs_dict.values():
+ # Futures may be present even with exactly-once delivery
+ # disabled, in transition periods after the setting is changed on
+ # the subscription.
+ if req.future:
+ req.future.set_result(AcknowledgeStatus.SUCCESS)
+ requests_completed.append(req)
+
+ return requests_completed, requests_to_retry
+
+ def heartbeat(self) -> bool:
+ """Sends a heartbeat request over the streaming pull RPC.
+
+ The request is empty by default, but may contain the current ack_deadline
+ if the self._exactly_once_enabled flag has changed.
+
+ Returns:
+ If a heartbeat request has actually been sent.
+ """
+ if self._rpc is not None and self._rpc.is_active:
+ send_new_ack_deadline = False
+ with self._exactly_once_enabled_lock:
+ send_new_ack_deadline = self._send_new_ack_deadline
+ self._send_new_ack_deadline = False
+
+ if send_new_ack_deadline:
+ request = gapic_types.StreamingPullRequest(
+ stream_ack_deadline_seconds=self._stream_ack_deadline
+ )
+ _LOGGER.debug(
+ "Sending new ack_deadline of %d seconds.", self._stream_ack_deadline
+ )
+ else:
+ request = gapic_types.StreamingPullRequest()
+
+ self._rpc.send(request)
+ return True
+
+ return False
+
+ def open(
+ self,
+ callback: Callable[["google.cloud.pubsub_v1.subscriber.message.Message"], Any],
+ on_callback_error: Callable[[Exception], Any],
+ ) -> None:
+ """Begin consuming messages.
+
+ Args:
+ callback:
+ A callback that will be called for each message received on the
+ stream.
+ on_callback_error:
+ A callable that will be called if an exception is raised in
+ the provided `callback`.
+ """
+ if self.is_active:
+ raise ValueError("This manager is already open.")
+
+ if self._closed:
+ raise ValueError("This manager has been closed and can not be re-used.")
+
+ self._callback = functools.partial(
+ _wrap_callback_errors, callback, on_callback_error
+ )
+
+ # Create the RPC
+ stream_ack_deadline_seconds = self._stream_ack_deadline
+
+ get_initial_request = functools.partial(
+ self._get_initial_request, stream_ack_deadline_seconds
+ )
+ self._rpc = bidi.ResumableBidiRpc(
+ start_rpc=self._client.streaming_pull,
+ initial_request=get_initial_request,
+ should_recover=self._should_recover,
+ should_terminate=self._should_terminate,
+ throttle_reopen=True,
+ )
+ self._rpc.add_done_callback(self._on_rpc_done)
+
+ _LOGGER.debug(
+ "Creating a stream, default ACK deadline set to {} seconds.".format(
+ self._stream_ack_deadline
+ )
+ )
+
+ # Create references to threads
+ assert self._scheduler is not None
+ scheduler_queue = self._scheduler.queue
+ self._dispatcher = dispatcher.Dispatcher(self, scheduler_queue)
+ self._consumer = bidi.BackgroundConsumer(self._rpc, self._on_response)
+ self._leaser = leaser.Leaser(self)
+ self._heartbeater = heartbeater.Heartbeater(self)
+
+ # Start the thread to pass the requests.
+ self._dispatcher.start()
+
+ # Start consuming messages.
+ self._consumer.start()
+
+ # Start the lease maintainer thread.
+ self._leaser.start()
+
+ # Start the stream heartbeater thread.
+ self._heartbeater.start()
+
+ def close(self, reason: Any = None) -> None:
+ """Stop consuming messages and shutdown all helper threads.
+
+ This method is idempotent. Additional calls will have no effect.
+
+ The method does not block, it delegates the shutdown operations to a background
+ thread.
+
+ Args:
+ reason:
+ The reason to close this. If ``None``, this is considered
+ an "intentional" shutdown. This is passed to the callbacks
+ specified via :meth:`add_close_callback`.
+ """
+ self._regular_shutdown_thread = threading.Thread(
+ name=_REGULAR_SHUTDOWN_THREAD_NAME,
+ daemon=True,
+ target=self._shutdown,
+ kwargs={"reason": reason},
+ )
+ self._regular_shutdown_thread.start()
+
+ def _shutdown(self, reason: Any = None) -> None:
+ """Run the actual shutdown sequence (stop the stream and all helper threads).
+
+ Args:
+ reason:
+ The reason to close the stream. If ``None``, this is considered
+ an "intentional" shutdown.
+ """
+ with self._closing:
+ if self._closed:
+ return
+
+ # Stop consuming messages.
+ if self.is_active:
+ _LOGGER.debug("Stopping consumer.")
+ assert self._consumer is not None
+ self._consumer.stop()
+ self._consumer = None
+
+ # Shutdown all helper threads
+ _LOGGER.debug("Stopping scheduler.")
+ assert self._scheduler is not None
+ dropped_messages = self._scheduler.shutdown(
+ await_msg_callbacks=self._await_callbacks_on_shutdown
+ )
+ self._scheduler = None
+
+ # Leaser and dispatcher reference each other through the shared
+ # StreamingPullManager instance, i.e. "self", thus do not set their
+ # references to None until both have been shut down.
+ #
+ # NOTE: Even if the dispatcher operates on an inactive leaser using
+ # the latter's add() and remove() methods, these have no impact on
+ # the stopped leaser (the leaser is never again re-started). Ditto
+ # for the manager's maybe_resume_consumer() / maybe_pause_consumer(),
+ # because the consumer gets shut down first.
+ _LOGGER.debug("Stopping leaser.")
+ assert self._leaser is not None
+ self._leaser.stop()
+
+ total = len(dropped_messages) + len(
+ self._messages_on_hold._messages_on_hold
+ )
+ _LOGGER.debug(f"NACK-ing all not-yet-dispatched messages (total: {total}).")
+ messages_to_nack = itertools.chain(
+ dropped_messages, self._messages_on_hold._messages_on_hold
+ )
+ for msg in messages_to_nack:
+ msg.nack()
+
+ _LOGGER.debug("Stopping dispatcher.")
+ assert self._dispatcher is not None
+ self._dispatcher.stop()
+ self._dispatcher = None
+ # dispatcher terminated, OK to dispose the leaser reference now
+ self._leaser = None
+
+ _LOGGER.debug("Stopping heartbeater.")
+ assert self._heartbeater is not None
+ self._heartbeater.stop()
+ self._heartbeater = None
+
+ self._rpc = None
+ self._closed = True
+ _LOGGER.debug("Finished stopping manager.")
+
+ for callback in self._close_callbacks:
+ callback(self, reason)
+
+ def _get_initial_request(
+ self, stream_ack_deadline_seconds: int
+ ) -> gapic_types.StreamingPullRequest:
+ """Return the initial request for the RPC.
+
+ This defines the initial request that must always be sent to Pub/Sub
+ immediately upon opening the subscription.
+
+ Args:
+ stream_ack_deadline_seconds:
+ The default message acknowledge deadline for the stream.
+
+ Returns:
+ A request suitable for being the first request on the stream (and not
+ suitable for any other purpose).
+ """
+ # Put the request together.
+ # We need to set streaming ack deadline, but it's not useful since we'll modack to send receipt
+ # anyway. Set to some big-ish value in case we modack late.
+ request = gapic_types.StreamingPullRequest(
+ stream_ack_deadline_seconds=stream_ack_deadline_seconds,
+ modify_deadline_ack_ids=[],
+ modify_deadline_seconds=[],
+ subscription=self._subscription,
+ client_id=self._client_id,
+ max_outstanding_messages=(
+ 0 if self._use_legacy_flow_control else self._flow_control.max_messages
+ ),
+ max_outstanding_bytes=(
+ 0 if self._use_legacy_flow_control else self._flow_control.max_bytes
+ ),
+ )
+
+ # Return the initial request.
+ return request
+
+ def _send_lease_modacks(
+ self, ack_ids: Iterable[str], ack_deadline: float, warn_on_invalid=True
+ ) -> List[str]:
+ exactly_once_enabled = False
+ with self._exactly_once_enabled_lock:
+ exactly_once_enabled = self._exactly_once_enabled
+ if exactly_once_enabled:
+ items = []
+ for ack_id in ack_ids:
+ future = futures.Future()
+ request = requests.ModAckRequest(ack_id, ack_deadline, future)
+ items.append(request)
+
+ assert self._dispatcher is not None
+ self._dispatcher.modify_ack_deadline(items)
+
+ expired_ack_ids = []
+ for req in items:
+ try:
+ assert req.future is not None
+ req.future.result()
+ except AcknowledgeError as ack_error:
+ if (
+ ack_error.error_code != AcknowledgeStatus.INVALID_ACK_ID
+ or warn_on_invalid
+ ):
+ _LOGGER.warning(
+ "AcknowledgeError when lease-modacking a message.",
+ exc_info=True,
+ )
+ if ack_error.error_code == AcknowledgeStatus.INVALID_ACK_ID:
+ expired_ack_ids.append(req.ack_id)
+ return expired_ack_ids
+ else:
+ items = [
+ requests.ModAckRequest(ack_id, self.ack_deadline, None)
+ for ack_id in ack_ids
+ ]
+ assert self._dispatcher is not None
+ self._dispatcher.modify_ack_deadline(items)
+ return []
+
+ def _exactly_once_delivery_enabled(self) -> bool:
+ """Whether exactly-once delivery is enabled for the subscription."""
+ with self._exactly_once_enabled_lock:
+ return self._exactly_once_enabled
+
+ def _on_response(self, response: gapic_types.StreamingPullResponse) -> None:
+ """Process all received Pub/Sub messages.
+
+ For each message, send a modified acknowledgment request to the
+ server. This prevents expiration of the message due to buffering by
+ gRPC or proxy/firewall. This makes the server and client expiration
+ timer closer to each other thus preventing the message being
+ redelivered multiple times.
+
+ After the messages have all had their ack deadline updated, execute
+ the callback for each message using the executor.
+ """
+ if response is None:
+ _LOGGER.debug(
+ "Response callback invoked with None, likely due to a "
+ "transport shutdown."
+ )
+ return
+
+ # IMPORTANT: Circumvent the wrapper class and operate on the raw underlying
+ # protobuf message to significantly gain on attribute access performance.
+ received_messages = response._pb.received_messages
+
+ _LOGGER.debug(
+ "Processing %s received message(s), currently on hold %s (bytes %s).",
+ len(received_messages),
+ self._messages_on_hold.size,
+ self._on_hold_bytes,
+ )
+
+ with self._exactly_once_enabled_lock:
+ if (
+ response.subscription_properties.exactly_once_delivery_enabled
+ != self._exactly_once_enabled
+ ):
+ self._exactly_once_enabled = (
+ response.subscription_properties.exactly_once_delivery_enabled
+ )
+ # Update ack_deadline, whose minimum depends on self._exactly_once_enabled
+ # This method acquires the self._ack_deadline_lock lock.
+ self._obtain_ack_deadline(maybe_update=True)
+ self._send_new_ack_deadline = True
+
+ # Immediately (i.e. without waiting for the auto lease management)
+ # modack the messages we received, as this tells the server that we've
+ # received them.
+ ack_id_gen = (message.ack_id for message in received_messages)
+ expired_ack_ids = set(
+ self._send_lease_modacks(
+ ack_id_gen, self.ack_deadline, warn_on_invalid=False
+ )
+ )
+
+ with self._pause_resume_lock:
+ assert self._scheduler is not None
+ assert self._leaser is not None
+
+ for received_message in received_messages:
+ if (
+ not self._exactly_once_delivery_enabled()
+ or received_message.ack_id not in expired_ack_ids
+ ):
+ message = google.cloud.pubsub_v1.subscriber.message.Message(
+ received_message.message,
+ received_message.ack_id,
+ received_message.delivery_attempt,
+ self._scheduler.queue,
+ self._exactly_once_delivery_enabled,
+ )
+ self._messages_on_hold.put(message)
+ self._on_hold_bytes += message.size
+ req = requests.LeaseRequest(
+ ack_id=message.ack_id,
+ byte_size=message.size,
+ ordering_key=message.ordering_key,
+ )
+ self._leaser.add([req])
+
+ self._maybe_release_messages()
+
+ self.maybe_pause_consumer()
+
+ def _should_recover(self, exception: BaseException) -> bool:
+ """Determine if an error on the RPC stream should be recovered.
+
+ If the exception is one of the retryable exceptions, this will signal
+ to the consumer thread that it should "recover" from the failure.
+
+ This will cause the stream to exit when it returns :data:`False`.
+
+ Returns:
+ Indicates if the caller should recover or shut down.
+ Will be :data:`True` if the ``exception`` is "acceptable", i.e.
+ in a list of retryable / idempotent exceptions.
+ """
+ exception = _wrap_as_exception(exception)
+ # If this is in the list of idempotent exceptions, then we want to
+ # recover.
+ if isinstance(exception, _RETRYABLE_STREAM_ERRORS):
+ _LOGGER.debug("Observed recoverable stream error %s", exception)
+ return True
+ _LOGGER.debug("Observed non-recoverable stream error %s", exception)
+ return False
+
+ def _should_terminate(self, exception: BaseException) -> bool:
+ """Determine if an error on the RPC stream should be terminated.
+
+ If the exception is one of the terminating exceptions, this will signal
+ to the consumer thread that it should terminate.
+
+ This will cause the stream to exit when it returns :data:`True`.
+
+ Returns:
+ Indicates if the caller should terminate or attempt recovery.
+ Will be :data:`True` if the ``exception`` is "acceptable", i.e.
+ in a list of terminating exceptions.
+ """
+ exception = _wrap_as_exception(exception)
+ if isinstance(exception, _TERMINATING_STREAM_ERRORS):
+ _LOGGER.debug("Observed terminating stream error %s", exception)
+ return True
+ _LOGGER.debug("Observed non-terminating stream error %s", exception)
+ return False
+
+ def _on_rpc_done(self, future: Any) -> None:
+ """Triggered whenever the underlying RPC terminates without recovery.
+
+ This is typically triggered from one of two threads: the background
+ consumer thread (when calling ``recv()`` produces a non-recoverable
+ error) or the grpc management thread (when cancelling the RPC).
+
+ This method is *non-blocking*. It will start another thread to deal
+ with shutting everything down. This is to prevent blocking in the
+ background consumer and preventing it from being ``joined()``.
+ """
+ _LOGGER.debug("RPC termination has signaled streaming pull manager shutdown.")
+ error = _wrap_as_exception(future)
+ thread = threading.Thread(
+ name=_RPC_ERROR_THREAD_NAME, target=self._shutdown, kwargs={"reason": error}
+ )
+ thread.daemon = True
+ thread.start()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
new file mode 100644
index 000000000000..9c12a0bfba3f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
@@ -0,0 +1,289 @@
+# Copyright 2019, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import os
+import pkg_resources
+import typing
+from typing import cast, Any, Callable, Optional, Sequence, Union
+import warnings
+
+from google.auth.credentials import AnonymousCredentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+from google.cloud.pubsub_v1 import types
+from google.cloud.pubsub_v1.subscriber import futures
+from google.cloud.pubsub_v1.subscriber._protocol import streaming_pull_manager
+from google.pubsub_v1.services.subscriber import client as subscriber_client
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1 import subscriber
+ from google.pubsub_v1.services.subscriber.transports.grpc import (
+ SubscriberGrpcTransport,
+ )
+
+
+try:
+ __version__ = pkg_resources.get_distribution("google-cloud-pubsub").version
+except pkg_resources.DistributionNotFound:
+ # Distribution might not be available if we are not running from within
+ # a PIP package.
+ __version__ = "0.0"
+
+
+class Client(subscriber_client.SubscriberClient):
+ """A subscriber client for Google Cloud Pub/Sub.
+
+ This creates an object that is capable of subscribing to messages.
+ Generally, you can instantiate this client with no arguments, and you
+ get sensible defaults.
+
+ Args:
+ kwargs: Any additional arguments provided are sent as keyword
+ keyword arguments to the underlying
+ :class:`~google.cloud.pubsub_v1.gapic.subscriber_client.SubscriberClient`.
+ Generally you should not need to set additional keyword
+ arguments. Optionally, regional endpoints can be set via
+ ``client_options`` that takes a single key-value pair that
+ defines the endpoint.
+
+ Example:
+
+ .. code-block:: python
+
+ from google.cloud import pubsub_v1
+
+ subscriber_client = pubsub_v1.SubscriberClient(
+ # Optional
+ client_options = {
+ "api_endpoint": REGIONAL_ENDPOINT
+ }
+ )
+ """
+
+ def __init__(self, **kwargs: Any):
+ # Sanity check: Is our goal to use the emulator?
+ # If so, create a grpc insecure channel with the emulator host
+ # as the target.
+ if os.environ.get("PUBSUB_EMULATOR_HOST"):
+ kwargs["client_options"] = {
+ "api_endpoint": os.environ.get("PUBSUB_EMULATOR_HOST")
+ }
+ kwargs["credentials"] = AnonymousCredentials()
+
+ # Instantiate the underlying GAPIC client.
+ super().__init__(**kwargs)
+ self._target = self._transport._host
+ self._closed = False
+
+ @classmethod
+ def from_service_account_file( # type: ignore[override]
+ cls, filename: str, **kwargs: Any
+ ) -> "Client":
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename: The path to the service account private key json file.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ A Subscriber :class:`~google.cloud.pubsub_v1.subscriber.client.Client`
+ instance that is the constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_file(filename)
+ kwargs["credentials"] = credentials
+ return cls(**kwargs)
+
+ from_service_account_json = from_service_account_file # type: ignore[assignment]
+
+ @property
+ def target(self) -> str:
+ """Return the target (where the API is).
+
+ Returns:
+ The location of the API.
+ """
+ return self._target
+
+ @property
+ def closed(self) -> bool:
+ """Return whether the client has been closed and cannot be used anymore.
+
+ .. versionadded:: 2.8.0
+ """
+ return self._closed
+
+ @property
+ def api(self):
+ """The underlying gapic API client.
+
+ .. versionchanged:: 2.10.0
+ Instead of a GAPIC ``SubscriberClient`` client instance, this property is a
+ proxy object to it with the same interface.
+
+ .. deprecated:: 2.10.0
+ Use the GAPIC methods and properties on the client instance directly
+ instead of through the :attr:`api` attribute.
+ """
+ msg = (
+ 'The "api" property only exists for backward compatibility, access its '
+ 'attributes directly thorugh the client instance (e.g. "client.foo" '
+ 'instead of "client.api.foo").'
+ )
+ warnings.warn(msg, category=DeprecationWarning)
+ return super()
+
+ def subscribe(
+ self,
+ subscription: str,
+ callback: Callable[["subscriber.message.Message"], Any],
+ flow_control: Union[types.FlowControl, Sequence] = (),
+ scheduler: Optional["subscriber.scheduler.ThreadScheduler"] = None,
+ use_legacy_flow_control: bool = False,
+ await_callbacks_on_shutdown: bool = False,
+ ) -> futures.StreamingPullFuture:
+ """Asynchronously start receiving messages on a given subscription.
+
+ This method starts a background thread to begin pulling messages from
+ a Pub/Sub subscription and scheduling them to be processed using the
+ provided ``callback``.
+
+ The ``callback`` will be called with an individual
+ :class:`google.cloud.pubsub_v1.subscriber.message.Message`. It is the
+ responsibility of the callback to either call ``ack()`` or ``nack()``
+ on the message when it finished processing. If an exception occurs in
+ the callback during processing, the exception is logged and the message
+ is ``nack()`` ed.
+
+ The ``flow_control`` argument can be used to control the rate of at
+ which messages are pulled. The settings are relatively conservative by
+ default to prevent "message hoarding" - a situation where the client
+ pulls a large number of messages but can not process them fast enough
+ leading it to "starve" other clients of messages. Increasing these
+ settings may lead to faster throughput for messages that do not take
+ a long time to process.
+
+ The ``use_legacy_flow_control`` argument disables enforcing flow control
+ settings at the Cloud Pub/Sub server, and only the client side flow control
+ will be enforced.
+
+ This method starts the receiver in the background and returns a
+ *Future* representing its execution. Waiting on the future (calling
+ ``result()``) will block forever or until a non-recoverable error
+ is encountered (such as loss of network connectivity). Cancelling the
+ future will signal the process to shutdown gracefully and exit.
+
+ .. note:: This uses Pub/Sub's *streaming pull* feature. This feature
+ properties that may be surprising. Please take a look at
+ https://cloud.google.com/pubsub/docs/pull#streamingpull for
+ more details on how streaming pull behaves compared to the
+ synchronous pull method.
+
+ Example:
+
+ .. code-block:: python
+
+ from google.cloud import pubsub_v1
+
+ subscriber_client = pubsub_v1.SubscriberClient()
+
+ # existing subscription
+ subscription = subscriber_client.subscription_path(
+ 'my-project-id', 'my-subscription')
+
+ def callback(message):
+ print(message)
+ message.ack()
+
+ future = subscriber_client.subscribe(
+ subscription, callback)
+
+ try:
+ future.result()
+ except KeyboardInterrupt:
+ future.cancel() # Trigger the shutdown.
+ future.result() # Block until the shutdown is complete.
+
+ Args:
+ subscription:
+ The name of the subscription. The subscription should have already been
+ created (for example, by using :meth:`create_subscription`).
+ callback:
+ The callback function. This function receives the message as
+ its only argument and will be called from a different thread/
+ process depending on the scheduling strategy.
+ flow_control:
+ The flow control settings. Use this to prevent situations where you are
+ inundated with too many messages at once.
+ scheduler:
+ An optional *scheduler* to use when executing the callback. This
+ controls how callbacks are executed concurrently. This object must not
+ be shared across multiple ``SubscriberClient`` instances.
+ use_legacy_flow_control (bool):
+ If set to ``True``, flow control at the Cloud Pub/Sub server is disabled,
+ though client-side flow control is still enabled. If set to ``False``
+ (default), both server-side and client-side flow control are enabled.
+ await_callbacks_on_shutdown:
+ If ``True``, after canceling the returned future, the latter's
+ ``result()`` method will block until the background stream and its
+ helper threads have been terminated, and all currently executing message
+ callbacks are done processing.
+
+ If ``False`` (default), the returned future's ``result()`` method will
+ not block after canceling the future. The method will instead return
+ immediately after the background stream and its helper threads have been
+ terminated, but some of the message callback threads might still be
+ running at that point.
+
+ Returns:
+ A future instance that can be used to manage the background stream.
+ """
+ flow_control = types.FlowControl(*flow_control)
+
+ manager = streaming_pull_manager.StreamingPullManager(
+ self,
+ subscription,
+ flow_control=flow_control,
+ scheduler=scheduler,
+ use_legacy_flow_control=use_legacy_flow_control,
+ await_callbacks_on_shutdown=await_callbacks_on_shutdown,
+ )
+
+ future = futures.StreamingPullFuture(manager)
+
+ manager.open(callback=callback, on_callback_error=future.set_exception)
+
+ return future
+
+ def close(self) -> None:
+ """Close the underlying channel to release socket resources.
+
+ After a channel has been closed, the client instance cannot be used
+ anymore.
+
+ This method is idempotent.
+ """
+ transport = cast("SubscriberGrpcTransport", self._transport)
+ transport.grpc_channel.close()
+ self._closed = True
+
+ def __enter__(self) -> "Client":
+ if self._closed:
+ raise RuntimeError("Closed subscriber cannot be used as context manager.")
+ return self
+
+ def __exit__(self, exc_type, exc_val, exc_tb):
+ self.close()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/exceptions.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/exceptions.py
new file mode 100644
index 000000000000..a5dad31a9998
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/exceptions.py
@@ -0,0 +1,44 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+from enum import Enum
+from google.api_core.exceptions import GoogleAPICallError
+from typing import Optional
+
+
+class AcknowledgeStatus(Enum):
+ SUCCESS = 1
+ PERMISSION_DENIED = 2
+ FAILED_PRECONDITION = 3
+ INVALID_ACK_ID = 4
+ OTHER = 5
+
+
+class AcknowledgeError(GoogleAPICallError):
+ """Error during ack/modack/nack operation on exactly-once-enabled subscription."""
+
+ def __init__(self, error_code: AcknowledgeStatus, info: Optional[str]):
+ self.error_code = error_code
+ self.info = info
+ message = None
+ if info:
+ message = str(self.error_code) + " : " + str(self.info)
+ else:
+ message = str(self.error_code)
+ super(AcknowledgeError, self).__init__(message)
+
+
+__all__ = ("AcknowledgeError",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
new file mode 100644
index 000000000000..f043b7eb517e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
@@ -0,0 +1,125 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import typing
+from typing import Any
+from typing import Union
+
+from google.cloud.pubsub_v1 import futures
+from google.cloud.pubsub_v1.subscriber.exceptions import AcknowledgeStatus
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud.pubsub_v1.subscriber._protocol.streaming_pull_manager import (
+ StreamingPullManager,
+ )
+
+
+class StreamingPullFuture(futures.Future):
+ """Represents a process that asynchronously performs streaming pull and
+ schedules messages to be processed.
+
+ This future is resolved when the process is stopped (via :meth:`cancel`) or
+ if it encounters an unrecoverable error. Calling `.result()` will cause
+ the calling thread to block indefinitely.
+ """
+
+ def __init__(self, manager: "StreamingPullManager"):
+ super(StreamingPullFuture, self).__init__()
+ self.__manager = manager
+ self.__manager.add_close_callback(self._on_close_callback)
+ self.__cancelled = False
+
+ def _on_close_callback(self, manager: "StreamingPullManager", result: Any):
+ if self.done():
+ # The future has already been resolved in a different thread,
+ # nothing to do on the streaming pull manager shutdown.
+ return
+
+ if result is None:
+ self.set_result(True)
+ else:
+ self.set_exception(result)
+
+ def cancel(self) -> bool:
+ """Stops pulling messages and shutdowns the background thread consuming
+ messages.
+
+ The method always returns ``True``, as the shutdown is always initiated.
+ However, if the background stream is already being shut down or the shutdown
+ has completed, this method is a no-op.
+
+ .. versionchanged:: 2.4.1
+ The method does not block anymore, it just triggers the shutdown and returns
+ immediately. To block until the background stream is terminated, call
+ :meth:`result()` after cancelling the future.
+
+ .. versionchanged:: 2.10.0
+ The method always returns ``True`` instead of ``None``.
+ """
+ # NOTE: We circumvent the base future's self._state to track the cancellation
+ # state, as this state has different meaning with streaming pull futures.
+ self.__cancelled = True
+ self.__manager.close()
+ return True
+
+ def cancelled(self) -> bool:
+ """
+ Returns:
+ ``True`` if the subscription has been cancelled.
+ """
+ return self.__cancelled
+
+
+class Future(futures.Future):
+ """This future object is for subscribe-side calls.
+
+ Calling :meth:`result` will resolve the future by returning the message
+ ID, unless an error occurs.
+ """
+
+ def cancel(self) -> bool:
+ """Actions in Pub/Sub generally may not be canceled.
+
+ This method always returns ``False``.
+ """
+ return False
+
+ def cancelled(self) -> bool:
+ """Actions in Pub/Sub generally may not be canceled.
+
+ This method always returns ``False``.
+ """
+ return False
+
+ def result(self, timeout: Union[int, float] = None) -> AcknowledgeStatus:
+ """Return a success code or raise an exception.
+
+ This blocks until the operation completes successfully and
+ returns the error code unless an exception is raised.
+
+ Args:
+ timeout: The number of seconds before this call
+ times out and raises TimeoutError.
+
+ Returns:
+ AcknowledgeStatus.SUCCESS if the operation succeeded.
+
+ Raises:
+ concurrent.futures.TimeoutError: If the request times out.
+ AcknowledgeError: If the operation did not succeed for another
+ reason.
+ """
+ return super().result(timeout=timeout)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
new file mode 100644
index 000000000000..c0a2e70ea965
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
@@ -0,0 +1,488 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import datetime as dt
+import json
+import math
+import time
+import typing
+from typing import Optional, Callable
+
+from google.cloud.pubsub_v1.subscriber._protocol import requests
+from google.cloud.pubsub_v1.subscriber import futures
+from google.cloud.pubsub_v1.subscriber.exceptions import AcknowledgeStatus
+
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ import datetime
+ import queue
+ from google.cloud.pubsub_v1 import types
+ from google.protobuf.internal import containers
+
+
+_MESSAGE_REPR = """\
+Message {{
+ data: {!r}
+ ordering_key: {!r}
+ attributes: {}
+}}"""
+
+_SUCCESS_FUTURE = futures.Future()
+_SUCCESS_FUTURE.set_result(AcknowledgeStatus.SUCCESS)
+
+
+def _indent(lines: str, prefix: str = " ") -> str:
+ """Indent some text.
+
+ Note that this is present as ``textwrap.indent``, but not in Python 2.
+
+ Args:
+ lines:
+ The newline delimited string to be indented.
+ prefix:
+ The prefix to indent each line with. Defaults to two spaces.
+
+ Returns:
+ The newly indented content.
+ """
+ indented = []
+ for line in lines.split("\n"):
+ indented.append(prefix + line)
+ return "\n".join(indented)
+
+
+class Message(object):
+ """A representation of a single Pub/Sub message.
+
+ The common way to interact with
+ :class:`~.pubsub_v1.subscriber.message.Message` objects is to receive
+ them in callbacks on subscriptions; most users should never have a need
+ to instantiate them by hand. (The exception to this is if you are
+ implementing a custom subclass to
+ :class:`~.pubsub_v1.subscriber._consumer.Consumer`.)
+
+ Attributes:
+ message_id:
+ The message ID. In general, you should not need to use this directly.
+ data:
+ The data in the message. Note that this will be a :class:`bytes`,
+ not a text string.
+ attributes:
+ The attributes sent along with the message. See :attr:`attributes` for more
+ information on this type.
+ publish_time:
+ The time that this message was originally published.
+ """
+
+ def __init__(
+ self,
+ message: "types.PubsubMessage._meta._pb", # type: ignore
+ ack_id: str,
+ delivery_attempt: int,
+ request_queue: "queue.Queue",
+ exactly_once_delivery_enabled_func: Callable[[], bool] = lambda: False,
+ ):
+ """Construct the Message.
+
+ .. note::
+
+ This class should not be constructed directly; it is the
+ responsibility of :class:`BasePolicy` subclasses to do so.
+
+ Args:
+ message:
+ The message received from Pub/Sub. For performance reasons it should be
+ the raw protobuf message normally wrapped by
+ :class:`~pubsub_v1.types.PubsubMessage`. A raw message can be obtained
+ from a :class:`~pubsub_v1.types.PubsubMessage` instance through the
+ latter's ``._pb`` attribute.
+ ack_id:
+ The ack_id received from Pub/Sub.
+ delivery_attempt:
+ The delivery attempt counter received from Pub/Sub if a DeadLetterPolicy
+ is set on the subscription, and zero otherwise.
+ request_queue:
+ A queue provided by the policy that can accept requests; the policy is
+ responsible for handling those requests.
+ exactly_once_delivery_enabled_func:
+ A Callable that returns whether exactly-once delivery is currently-enabled. Defaults to a lambda that always returns False.
+ """
+ self._message = message
+ self._ack_id = ack_id
+ self._delivery_attempt = delivery_attempt if delivery_attempt > 0 else None
+ self._request_queue = request_queue
+ self._exactly_once_delivery_enabled_func = exactly_once_delivery_enabled_func
+ self.message_id = message.message_id
+
+ # The instantiation time is the time that this message
+ # was received. Tracking this provides us a way to be smart about
+ # the default lease deadline.
+ self._received_timestamp = time.time()
+
+ # Store the message attributes directly to speed up attribute access, i.e.
+ # to avoid two lookups if self._message. pattern was used in
+ # properties.
+ self._attributes = message.attributes
+ self._data = message.data
+ self._publish_time = dt.datetime.fromtimestamp(
+ message.publish_time.seconds + message.publish_time.nanos / 1e9,
+ tz=dt.timezone.utc,
+ )
+ self._ordering_key = message.ordering_key
+ self._size = message.ByteSize()
+
+ def __repr__(self):
+ # Get an abbreviated version of the data.
+ abbv_data = self._message.data
+ if len(abbv_data) > 50:
+ abbv_data = abbv_data[:50] + b"..."
+
+ pretty_attrs = json.dumps(
+ dict(self.attributes), indent=2, separators=(",", ": "), sort_keys=True
+ )
+ pretty_attrs = _indent(pretty_attrs)
+ # We don't actually want the first line indented.
+ pretty_attrs = pretty_attrs.lstrip()
+ return _MESSAGE_REPR.format(abbv_data, str(self.ordering_key), pretty_attrs)
+
+ @property
+ def attributes(self) -> "containers.ScalarMap":
+ """Return the attributes of the underlying Pub/Sub Message.
+
+ .. warning::
+
+ A ``ScalarMap`` behaves slightly differently than a
+ ``dict``. For a Pub / Sub message this is a ``string->string`` map.
+ When trying to access a value via ``map['key']``, if the key is
+ not in the map, then the default value for the string type will
+ be returned, which is an empty string. It may be more intuitive
+ to just cast the map to a ``dict`` or to one use ``map.get``.
+
+ Returns:
+ The message's attributes. This is a ``dict``-like object provided by
+ ``google.protobuf``.
+ """
+ return self._attributes
+
+ @property
+ def data(self) -> bytes:
+ """Return the data for the underlying Pub/Sub Message.
+
+ Returns:
+ The message data. This is always a bytestring; if you want a text string,
+ call :meth:`bytes.decode`.
+ """
+ return self._data
+
+ @property
+ def publish_time(self) -> "datetime.datetime":
+ """Return the time that the message was originally published.
+
+ Returns:
+ The date and time that the message was published.
+ """
+ return self._publish_time
+
+ @property
+ def ordering_key(self) -> str:
+ """The ordering key used to publish the message."""
+ return self._ordering_key
+
+ @property
+ def size(self) -> int:
+ """Return the size of the underlying message, in bytes."""
+ return self._size
+
+ @property
+ def ack_id(self) -> str:
+ """the ID used to ack the message."""
+ return self._ack_id
+
+ @property
+ def delivery_attempt(self) -> Optional[int]:
+ """The delivery attempt counter is 1 + (the sum of number of NACKs
+ and number of ack_deadline exceeds) for this message. It is set to None
+ if a DeadLetterPolicy is not set on the subscription.
+
+ A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
+ exceeds event is whenever a message is not acknowledged within
+ ack_deadline. Note that ack_deadline is initially
+ Subscription.ackDeadlineSeconds, but may get extended automatically by
+ the client library.
+
+ The first delivery of a given message will have this value as 1. The value
+ is calculated at best effort and is approximate.
+
+ Returns:
+ The delivery attempt counter or ``None``.
+ """
+ return self._delivery_attempt
+
+ def ack(self) -> None:
+ """Acknowledge the given message.
+
+ Acknowledging a message in Pub/Sub means that you are done
+ with it, and it will not be delivered to this subscription again.
+ You should avoid acknowledging messages until you have
+ *finished* processing them, so that in the event of a failure,
+ you receive the message again.
+
+ .. warning::
+ Acks in Pub/Sub are best effort. You should always
+ ensure that your processing code is idempotent, as you may
+ receive any given message more than once. If you need strong
+ guarantees about acks and re-deliveres, enable exactly-once
+ delivery on your subscription and use the `ack_with_response`
+ method instead. Exactly once delivery is a preview feature.
+ For more details, see:
+ https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ """
+ time_to_ack = math.ceil(time.time() - self._received_timestamp)
+ self._request_queue.put(
+ requests.AckRequest(
+ ack_id=self._ack_id,
+ byte_size=self.size,
+ time_to_ack=time_to_ack,
+ ordering_key=self.ordering_key,
+ future=None,
+ )
+ )
+
+ def ack_with_response(self) -> "futures.Future":
+ """Acknowledge the given message.
+
+ Acknowledging a message in Pub/Sub means that you are done
+ with it, and it will not be delivered to this subscription again.
+ You should avoid acknowledging messages until you have
+ *finished* processing them, so that in the event of a failure,
+ you receive the message again.
+
+ If exactly-once delivery is NOT enabled on the subscription, the
+ future returns immediately with an AcknowledgeStatus.SUCCESS.
+ Since acks in Cloud Pub/Sub are best effort when exactly-once
+ delivery is disabled, the message may be re-delivered. Because
+ re-deliveries are possible, you should ensure that your processing
+ code is idempotent, as you may receive any given message more than
+ once.
+
+ If exactly-once delivery is enabled on the subscription, the
+ future returned by this method tracks the state of acknowledgement
+ operation. If the future completes successfully, the message is
+ guaranteed NOT to be re-delivered. Otherwise, the future will
+ contain an exception with more details about the failure and the
+ message may be re-delivered.
+
+ Exactly once delivery is a preview feature. For more details,
+ see https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ Returns:
+ A :class:`~google.cloud.pubsub_v1.subscriber.futures.Future`
+ instance that conforms to Python Standard library's
+ :class:`~concurrent.futures.Future` interface (but not an
+ instance of that class). Call `result()` to get the result
+ of the operation; upon success, a
+ pubsub_v1.subscriber.exceptions.AcknowledgeStatus.SUCCESS
+ will be returned and upon an error, an
+ pubsub_v1.subscriber.exceptions.AcknowledgeError exception
+ will be thrown.
+ """
+ req_future: Optional[futures.Future]
+ if self._exactly_once_delivery_enabled_func():
+ future = futures.Future()
+ req_future = future
+ else:
+ future = _SUCCESS_FUTURE
+ req_future = None
+ time_to_ack = math.ceil(time.time() - self._received_timestamp)
+ self._request_queue.put(
+ requests.AckRequest(
+ ack_id=self._ack_id,
+ byte_size=self.size,
+ time_to_ack=time_to_ack,
+ ordering_key=self.ordering_key,
+ future=req_future,
+ )
+ )
+ return future
+
+ def drop(self) -> None:
+ """Release the message from lease management.
+
+ This informs the policy to no longer hold on to the lease for this
+ message. Pub/Sub will re-deliver the message if it is not acknowledged
+ before the existing lease expires.
+
+ .. warning::
+ For most use cases, the only reason to drop a message from
+ lease management is on `ack` or `nack`; this library
+ automatically drop()s the message on `ack` or `nack`. You probably
+ do not want to call this method directly.
+ """
+ self._request_queue.put(
+ requests.DropRequest(
+ ack_id=self._ack_id, byte_size=self.size, ordering_key=self.ordering_key
+ )
+ )
+
+ def modify_ack_deadline(self, seconds: int) -> None:
+ """Resets the deadline for acknowledgement.
+
+ New deadline will be the given value of seconds from now.
+
+ The default implementation handles automatically modacking received messages for you;
+ you should not need to manually deal with setting ack deadlines. The exception case is
+ if you are implementing your own custom subclass of
+ :class:`~.pubsub_v1.subcriber._consumer.Consumer`.
+
+ Args:
+ seconds:
+ The number of seconds to set the lease deadline to. This should be
+ between 0 and 600. Due to network latency, values below 10 are advised
+ against.
+ """
+ self._request_queue.put(
+ requests.ModAckRequest(ack_id=self._ack_id, seconds=seconds, future=None)
+ )
+
+ def modify_ack_deadline_with_response(self, seconds: int) -> "futures.Future":
+ """Resets the deadline for acknowledgement and returns the response
+ status via a future.
+
+ New deadline will be the given value of seconds from now.
+
+ The default implementation handles automatically modacking received messages for you;
+ you should not need to manually deal with setting ack deadlines. The exception case is
+ if you are implementing your own custom subclass of
+ :class:`~.pubsub_v1.subcriber._consumer.Consumer`.
+
+ If exactly-once delivery is NOT enabled on the subscription, the
+ future returns immediately with an AcknowledgeStatus.SUCCESS.
+ Since modify-ack-deadline operations in Cloud Pub/Sub are best effort
+ when exactly-once delivery is disabled, the message may be re-delivered
+ within the set deadline.
+
+ If exactly-once delivery is enabled on the subscription, the
+ future returned by this method tracks the state of the
+ modify-ack-deadline operation. If the future completes successfully,
+ the message is guaranteed NOT to be re-delivered within the new deadline.
+ Otherwise, the future will contain an exception with more details about
+ the failure and the message will be redelivered according to its
+ currently-set ack deadline.
+
+ Exactly once delivery is a preview feature. For more details,
+ see https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ Args:
+ seconds:
+ The number of seconds to set the lease deadline to. This should be
+ between 0 and 600. Due to network latency, values below 10 are advised
+ against.
+ Returns:
+ A :class:`~google.cloud.pubsub_v1.subscriber.futures.Future`
+ instance that conforms to Python Standard library's
+ :class:`~concurrent.futures.Future` interface (but not an
+ instance of that class). Call `result()` to get the result
+ of the operation; upon success, a
+ pubsub_v1.subscriber.exceptions.AcknowledgeStatus.SUCCESS
+ will be returned and upon an error, an
+ pubsub_v1.subscriber.exceptions.AcknowledgeError exception
+ will be thrown.
+
+ """
+ req_future: Optional[futures.Future]
+ if self._exactly_once_delivery_enabled_func():
+ future = futures.Future()
+ req_future = future
+ else:
+ future = _SUCCESS_FUTURE
+ req_future = None
+
+ self._request_queue.put(
+ requests.ModAckRequest(
+ ack_id=self._ack_id, seconds=seconds, future=req_future
+ )
+ )
+
+ return future
+
+ def nack(self) -> None:
+ """Decline to acknowledge the given message.
+
+ This will cause the message to be re-delivered to subscribers. Re-deliveries
+ may take place immediately or after a delay, and may arrive at this subscriber
+ or another.
+ """
+ self._request_queue.put(
+ requests.NackRequest(
+ ack_id=self._ack_id,
+ byte_size=self.size,
+ ordering_key=self.ordering_key,
+ future=None,
+ )
+ )
+
+ def nack_with_response(self) -> "futures.Future":
+ """Decline to acknowledge the given message, returning the response status via
+ a future.
+
+ This will cause the message to be re-delivered to subscribers. Re-deliveries
+ may take place immediately or after a delay, and may arrive at this subscriber
+ or another.
+
+ If exactly-once delivery is NOT enabled on the subscription, the
+ future returns immediately with an AcknowledgeStatus.SUCCESS.
+
+ If exactly-once delivery is enabled on the subscription, the
+ future returned by this method tracks the state of the
+ nack operation. If the future completes successfully,
+ the future's result will be an AcknowledgeStatus.SUCCESS.
+ Otherwise, the future will contain an exception with more details about
+ the failure.
+
+ Exactly once delivery is a preview feature. For more details,
+ see https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ Returns:
+ A :class:`~google.cloud.pubsub_v1.subscriber.futures.Future`
+ instance that conforms to Python Standard library's
+ :class:`~concurrent.futures.Future` interface (but not an
+ instance of that class). Call `result()` to get the result
+ of the operation; upon success, a
+ pubsub_v1.subscriber.exceptions.AcknowledgeStatus.SUCCESS
+ will be returned and upon an error, an
+ pubsub_v1.subscriber.exceptions.AcknowledgeError exception
+ will be thrown.
+
+ """
+ req_future: Optional[futures.Future]
+ if self._exactly_once_delivery_enabled_func():
+ future = futures.Future()
+ req_future = future
+ else:
+ future = _SUCCESS_FUTURE
+ req_future = None
+
+ self._request_queue.put(
+ requests.NackRequest(
+ ack_id=self._ack_id,
+ byte_size=self.size,
+ ordering_key=self.ordering_key,
+ future=req_future,
+ )
+ )
+
+ return future
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
new file mode 100644
index 000000000000..ca270a077dfb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
@@ -0,0 +1,170 @@
+# Copyright 2018, Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Schedulers provide means to *schedule* callbacks asynchronously.
+
+These are used by the subscriber to call the user-provided callback to process
+each message.
+"""
+
+import abc
+import concurrent.futures
+import queue
+import typing
+from typing import Callable, List, Optional
+import warnings
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from google.cloud import pubsub_v1
+
+
+class Scheduler(metaclass=abc.ABCMeta):
+ """Abstract base class for schedulers.
+
+ Schedulers are used to schedule callbacks asynchronously.
+ """
+
+ @property
+ @abc.abstractmethod
+ def queue(self) -> queue.Queue: # pragma: NO COVER
+ """Queue: A concurrency-safe queue specific to the underlying
+ concurrency implementation.
+
+ This queue is used to send messages *back* to the scheduling actor.
+ """
+ raise NotImplementedError
+
+ @abc.abstractmethod
+ def schedule(self, callback: Callable, *args, **kwargs) -> None: # pragma: NO COVER
+ """Schedule the callback to be called asynchronously.
+
+ Args:
+ callback: The function to call.
+ args: Positional arguments passed to the callback.
+ kwargs: Key-word arguments passed to the callback.
+
+ Returns:
+ None
+ """
+ raise NotImplementedError
+
+ @abc.abstractmethod
+ def shutdown(
+ self, await_msg_callbacks: bool = False
+ ) -> List["pubsub_v1.subscriber.message.Message"]: # pragma: NO COVER
+ """Shuts down the scheduler and immediately end all pending callbacks.
+
+ Args:
+ await_msg_callbacks:
+ If ``True``, the method will block until all currently executing
+ callbacks are done processing. If ``False`` (default), the
+ method will not wait for the currently running callbacks to complete.
+
+ Returns:
+ The messages submitted to the scheduler that were not yet dispatched
+ to their callbacks.
+ It is assumed that each message was submitted to the scheduler as the
+ first positional argument to the provided callback.
+ """
+ raise NotImplementedError
+
+
+def _make_default_thread_pool_executor() -> concurrent.futures.ThreadPoolExecutor:
+ return concurrent.futures.ThreadPoolExecutor(
+ max_workers=10, thread_name_prefix="ThreadPoolExecutor-ThreadScheduler"
+ )
+
+
+class ThreadScheduler(Scheduler):
+ """A thread pool-based scheduler. It must not be shared across
+ SubscriberClients.
+
+ This scheduler is useful in typical I/O-bound message processing.
+
+ Args:
+ executor:
+ An optional executor to use. If not specified, a default one
+ will be created.
+ """
+
+ def __init__(
+ self, executor: Optional[concurrent.futures.ThreadPoolExecutor] = None
+ ):
+ self._queue: queue.Queue = queue.Queue()
+ if executor is None:
+ self._executor = _make_default_thread_pool_executor()
+ else:
+ self._executor = executor
+
+ @property
+ def queue(self):
+ """Queue: A thread-safe queue used for communication between callbacks
+ and the scheduling thread."""
+ return self._queue
+
+ def schedule(self, callback: Callable, *args, **kwargs) -> None:
+ """Schedule the callback to be called asynchronously in a thread pool.
+
+ Args:
+ callback: The function to call.
+ args: Positional arguments passed to the callback.
+ kwargs: Key-word arguments passed to the callback.
+
+ Returns:
+ None
+ """
+ try:
+ self._executor.submit(callback, *args, **kwargs)
+ except RuntimeError:
+ warnings.warn(
+ "Scheduling a callback after executor shutdown.",
+ category=RuntimeWarning,
+ stacklevel=2,
+ )
+
+ def shutdown(
+ self, await_msg_callbacks: bool = False
+ ) -> List["pubsub_v1.subscriber.message.Message"]:
+ """Shut down the scheduler and immediately end all pending callbacks.
+
+ Args:
+ await_msg_callbacks:
+ If ``True``, the method will block until all currently executing
+ executor threads are done processing. If ``False`` (default), the
+ method will not wait for the currently running threads to complete.
+
+ Returns:
+ The messages submitted to the scheduler that were not yet dispatched
+ to their callbacks.
+ It is assumed that each message was submitted to the scheduler as the
+ first positional argument to the provided callback.
+ """
+ dropped_messages = []
+
+ # Drop all pending item from the executor. Without this, the executor will also
+ # try to process any pending work items before termination, which is undesirable.
+ #
+ # TODO: Replace the logic below by passing `cancel_futures=True` to shutdown()
+ # once we only need to support Python 3.9+.
+ try:
+ while True:
+ work_item = self._executor._work_queue.get(block=False)
+ if work_item is None: # Exceutor in shutdown mode.
+ continue
+ dropped_messages.append(work_item.args[0])
+ except queue.Empty:
+ pass
+
+ self._executor.shutdown(wait=await_msg_callbacks)
+ return dropped_messages
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
new file mode 100644
index 000000000000..109d4aadc8a7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
@@ -0,0 +1,238 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import
+
+import collections
+import enum
+import inspect
+import sys
+import typing
+from typing import Dict, NamedTuple, Union
+
+import proto # type: ignore
+
+from google.api import http_pb2 # type: ignore
+from google.api_core import gapic_v1
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2
+from google.iam.v1.logging import audit_data_pb2 # type: ignore
+from google.protobuf import descriptor_pb2
+from google.protobuf import duration_pb2
+from google.protobuf import empty_pb2
+from google.protobuf import field_mask_pb2
+from google.protobuf import timestamp_pb2
+
+from google.api_core.protobuf_helpers import get_messages
+
+from google.pubsub_v1.types import pubsub as pubsub_gapic_types
+
+
+if typing.TYPE_CHECKING: # pragma: NO COVER
+ from types import ModuleType
+ from google.pubsub_v1 import types as gapic_types
+ from google.pubsub_v1.services.publisher.client import OptionalRetry
+
+ # TODO: Eventually implement OptionalTimeout in the GAPIC code generator and import
+ # it from the generated code. It's the same solution that is used for OptionalRetry.
+ # https://github.com/googleapis/gapic-generator-python/pull/1032/files
+ # https://github.com/googleapis/gapic-generator-python/pull/1065/files
+ if hasattr(gapic_v1.method, "_MethodDefault"):
+ # _MethodDefault was only added in google-api-core==2.2.2
+ OptionalTimeout = Union[gapic_types.TimeoutType, gapic_v1.method._MethodDefault]
+ else:
+ OptionalTimeout = Union[gapic_types.TimeoutType, object] # type: ignore
+
+
+# Define the default values for batching.
+#
+# This class is used when creating a publisher or subscriber client, and
+# these settings can be altered to tweak Pub/Sub behavior.
+# The defaults should be fine for most use cases.
+class BatchSettings(NamedTuple):
+ """The settings for batch publishing the messages."""
+
+ max_bytes: int = 1 * 1000 * 1000 # 1 MB
+ (
+ "The maximum total size of the messages to collect before automatically "
+ "publishing the batch, including any byte size overhead of the publish "
+ "request itself. The maximum value is bound by the server-side limit of "
+ "10_000_000 bytes."
+ )
+
+ max_latency: float = 0.01 # 10 ms
+ (
+ "The maximum number of seconds to wait for additional messages before "
+ "automatically publishing the batch."
+ )
+
+ max_messages: int = 100
+ (
+ "The maximum number of messages to collect before automatically "
+ "publishing the batch."
+ )
+
+
+class LimitExceededBehavior(str, enum.Enum):
+ """The possible actions when exceeding the publish flow control limits."""
+
+ IGNORE = "ignore"
+ BLOCK = "block"
+ ERROR = "error"
+
+
+class PublishFlowControl(NamedTuple):
+ """The client flow control settings for message publishing."""
+
+ message_limit: int = 10 * BatchSettings.__new__.__defaults__[2] # type: ignore
+ """The maximum number of messages awaiting to be published."""
+
+ byte_limit: int = 10 * BatchSettings.__new__.__defaults__[0] # type: ignore
+ """The maximum total size of messages awaiting to be published."""
+
+ limit_exceeded_behavior: LimitExceededBehavior = LimitExceededBehavior.IGNORE
+ """The action to take when publish flow control limits are exceeded."""
+
+
+# Define the default publisher options.
+#
+# This class is used when creating a publisher client to pass in options
+# to enable/disable features.
+class PublisherOptions(NamedTuple):
+ """The options for the publisher client."""
+
+ enable_message_ordering: bool = False
+ """Whether to order messages in a batch by a supplied ordering key."""
+
+ flow_control: PublishFlowControl = PublishFlowControl()
+ (
+ "Flow control settings for message publishing by the client. By default "
+ "the publisher client does not do any throttling."
+ )
+
+ retry: "OptionalRetry" = gapic_v1.method.DEFAULT # use api_core default
+ (
+ "Retry settings for message publishing by the client. This should be "
+ "an instance of :class:`google.api_core.retry.Retry`."
+ )
+
+ timeout: "OptionalTimeout" = gapic_v1.method.DEFAULT # use api_core default
+ (
+ "Timeout settings for message publishing by the client. It should be "
+ "compatible with :class:`~.pubsub_v1.types.TimeoutType`."
+ )
+
+
+# Define the type class and default values for flow control settings.
+#
+# This class is used when creating a publisher or subscriber client, and
+# these settings can be altered to tweak Pub/Sub behavior.
+# The defaults should be fine for most use cases.
+class FlowControl(NamedTuple):
+ """The settings for controlling the rate at which messages are pulled
+ with an asynchronous subscription.
+ """
+
+ max_bytes: int = 100 * 1024 * 1024 # 100 MiB
+ (
+ "The maximum total size of received - but not yet processed - messages "
+ "before pausing the message stream."
+ )
+
+ max_messages: int = 1000
+ (
+ "The maximum number of received - but not yet processed - messages before "
+ "pausing the message stream."
+ )
+
+ max_lease_duration: float = 1 * 60 * 60 # 1 hour
+ (
+ "The maximum amount of time in seconds to hold a lease on a message "
+ "before dropping it from the lease management."
+ )
+
+ min_duration_per_lease_extension: float = 0
+ (
+ "The min amount of time in seconds for a single lease extension attempt. "
+ "Must be between 10 and 600 (inclusive). Ignored by default, but set to "
+ "60 seconds if the subscription has exactly-once delivery enabled."
+ )
+
+ max_duration_per_lease_extension: float = 0 # disabled by default
+ (
+ "The max amount of time in seconds for a single lease extension attempt. "
+ "Bounds the delay before a message redelivery if the subscriber "
+ "fails to extend the deadline. Must be between 10 and 600 (inclusive). Ignored "
+ "if set to 0."
+ )
+
+
+# The current api core helper does not find new proto messages of type proto.Message,
+# thus we need our own helper. Adjusted from
+# https://github.com/googleapis/python-api-core/blob/8595f620e7d8295b6a379d6fd7979af3bef717e2/google/api_core/protobuf_helpers.py#L101-L118
+def _get_protobuf_messages(module: "ModuleType") -> Dict[str, proto.Message]:
+ """Discover all protobuf Message classes in a given import module.
+
+ Args:
+ module (module): A Python module; :func:`dir` will be run against this
+ module to find Message subclasses.
+
+ Returns:
+ dict[str, proto.Message]: A dictionary with the
+ Message class names as keys, and the Message subclasses themselves
+ as values.
+ """
+ answer = collections.OrderedDict()
+ for name in dir(module):
+ candidate = getattr(module, name)
+ if inspect.isclass(candidate) and issubclass(candidate, proto.Message):
+ answer[name] = candidate
+ return answer
+
+
+_shared_modules = [
+ http_pb2,
+ iam_policy_pb2,
+ policy_pb2,
+ audit_data_pb2,
+ descriptor_pb2,
+ duration_pb2,
+ empty_pb2,
+ field_mask_pb2,
+ timestamp_pb2,
+]
+
+_local_modules = [pubsub_gapic_types]
+
+names = [
+ "BatchSettings",
+ "LimitExceededBehavior",
+ "PublishFlowControl",
+ "PublisherOptions",
+ "FlowControl",
+]
+
+for module in _shared_modules:
+ for name, message in get_messages(module).items():
+ setattr(sys.modules[__name__], name, message)
+ names.append(name)
+
+for module in _local_modules:
+ for name, message in _get_protobuf_messages(module).items():
+ message.__module__ = "google.cloud.pubsub_v1.types"
+ setattr(sys.modules[__name__], name, message)
+ names.append(name)
+
+
+__all__ = tuple(sorted(names))
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub/__init__.py
new file mode 100644
index 000000000000..7c94c23082b0
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub/__init__.py
@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from google.pubsub_v1.services.publisher.client import PublisherClient
+from google.pubsub_v1.services.publisher.async_client import PublisherAsyncClient
+from google.pubsub_v1.services.schema_service.client import SchemaServiceClient
+from google.pubsub_v1.services.schema_service.async_client import (
+ SchemaServiceAsyncClient,
+)
+from google.pubsub_v1.services.subscriber.client import SubscriberClient
+from google.pubsub_v1.services.subscriber.async_client import SubscriberAsyncClient
+
+from google.pubsub_v1.types.pubsub import AcknowledgeRequest
+from google.pubsub_v1.types.pubsub import BigQueryConfig
+from google.pubsub_v1.types.pubsub import CreateSnapshotRequest
+from google.pubsub_v1.types.pubsub import DeadLetterPolicy
+from google.pubsub_v1.types.pubsub import DeleteSnapshotRequest
+from google.pubsub_v1.types.pubsub import DeleteSubscriptionRequest
+from google.pubsub_v1.types.pubsub import DeleteTopicRequest
+from google.pubsub_v1.types.pubsub import DetachSubscriptionRequest
+from google.pubsub_v1.types.pubsub import DetachSubscriptionResponse
+from google.pubsub_v1.types.pubsub import ExpirationPolicy
+from google.pubsub_v1.types.pubsub import GetSnapshotRequest
+from google.pubsub_v1.types.pubsub import GetSubscriptionRequest
+from google.pubsub_v1.types.pubsub import GetTopicRequest
+from google.pubsub_v1.types.pubsub import ListSnapshotsRequest
+from google.pubsub_v1.types.pubsub import ListSnapshotsResponse
+from google.pubsub_v1.types.pubsub import ListSubscriptionsRequest
+from google.pubsub_v1.types.pubsub import ListSubscriptionsResponse
+from google.pubsub_v1.types.pubsub import ListTopicSnapshotsRequest
+from google.pubsub_v1.types.pubsub import ListTopicSnapshotsResponse
+from google.pubsub_v1.types.pubsub import ListTopicsRequest
+from google.pubsub_v1.types.pubsub import ListTopicsResponse
+from google.pubsub_v1.types.pubsub import ListTopicSubscriptionsRequest
+from google.pubsub_v1.types.pubsub import ListTopicSubscriptionsResponse
+from google.pubsub_v1.types.pubsub import MessageStoragePolicy
+from google.pubsub_v1.types.pubsub import ModifyAckDeadlineRequest
+from google.pubsub_v1.types.pubsub import ModifyPushConfigRequest
+from google.pubsub_v1.types.pubsub import PublishRequest
+from google.pubsub_v1.types.pubsub import PublishResponse
+from google.pubsub_v1.types.pubsub import PubsubMessage
+from google.pubsub_v1.types.pubsub import PullRequest
+from google.pubsub_v1.types.pubsub import PullResponse
+from google.pubsub_v1.types.pubsub import PushConfig
+from google.pubsub_v1.types.pubsub import ReceivedMessage
+from google.pubsub_v1.types.pubsub import RetryPolicy
+from google.pubsub_v1.types.pubsub import SchemaSettings
+from google.pubsub_v1.types.pubsub import SeekRequest
+from google.pubsub_v1.types.pubsub import SeekResponse
+from google.pubsub_v1.types.pubsub import Snapshot
+from google.pubsub_v1.types.pubsub import StreamingPullRequest
+from google.pubsub_v1.types.pubsub import StreamingPullResponse
+from google.pubsub_v1.types.pubsub import Subscription
+from google.pubsub_v1.types.pubsub import Topic
+from google.pubsub_v1.types.pubsub import UpdateSnapshotRequest
+from google.pubsub_v1.types.pubsub import UpdateSubscriptionRequest
+from google.pubsub_v1.types.pubsub import UpdateTopicRequest
+from google.pubsub_v1.types.schema import CreateSchemaRequest
+from google.pubsub_v1.types.schema import DeleteSchemaRequest
+from google.pubsub_v1.types.schema import GetSchemaRequest
+from google.pubsub_v1.types.schema import ListSchemasRequest
+from google.pubsub_v1.types.schema import ListSchemasResponse
+from google.pubsub_v1.types.schema import Schema
+from google.pubsub_v1.types.schema import ValidateMessageRequest
+from google.pubsub_v1.types.schema import ValidateMessageResponse
+from google.pubsub_v1.types.schema import ValidateSchemaRequest
+from google.pubsub_v1.types.schema import ValidateSchemaResponse
+from google.pubsub_v1.types.schema import Encoding
+from google.pubsub_v1.types.schema import SchemaView
+
+__all__ = (
+ "PublisherClient",
+ "PublisherAsyncClient",
+ "SchemaServiceClient",
+ "SchemaServiceAsyncClient",
+ "SubscriberClient",
+ "SubscriberAsyncClient",
+ "AcknowledgeRequest",
+ "BigQueryConfig",
+ "CreateSnapshotRequest",
+ "DeadLetterPolicy",
+ "DeleteSnapshotRequest",
+ "DeleteSubscriptionRequest",
+ "DeleteTopicRequest",
+ "DetachSubscriptionRequest",
+ "DetachSubscriptionResponse",
+ "ExpirationPolicy",
+ "GetSnapshotRequest",
+ "GetSubscriptionRequest",
+ "GetTopicRequest",
+ "ListSnapshotsRequest",
+ "ListSnapshotsResponse",
+ "ListSubscriptionsRequest",
+ "ListSubscriptionsResponse",
+ "ListTopicSnapshotsRequest",
+ "ListTopicSnapshotsResponse",
+ "ListTopicsRequest",
+ "ListTopicsResponse",
+ "ListTopicSubscriptionsRequest",
+ "ListTopicSubscriptionsResponse",
+ "MessageStoragePolicy",
+ "ModifyAckDeadlineRequest",
+ "ModifyPushConfigRequest",
+ "PublishRequest",
+ "PublishResponse",
+ "PubsubMessage",
+ "PullRequest",
+ "PullResponse",
+ "PushConfig",
+ "ReceivedMessage",
+ "RetryPolicy",
+ "SchemaSettings",
+ "SeekRequest",
+ "SeekResponse",
+ "Snapshot",
+ "StreamingPullRequest",
+ "StreamingPullResponse",
+ "Subscription",
+ "Topic",
+ "UpdateSnapshotRequest",
+ "UpdateSubscriptionRequest",
+ "UpdateTopicRequest",
+ "CreateSchemaRequest",
+ "DeleteSchemaRequest",
+ "GetSchemaRequest",
+ "ListSchemasRequest",
+ "ListSchemasResponse",
+ "Schema",
+ "ValidateMessageRequest",
+ "ValidateMessageResponse",
+ "ValidateSchemaRequest",
+ "ValidateSchemaResponse",
+ "Encoding",
+ "SchemaView",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub/py.typed b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub/py.typed
new file mode 100644
index 000000000000..1cec9a5ba1ab
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub/py.typed
@@ -0,0 +1,2 @@
+# Marker file for PEP 561.
+# The google-cloud-pubsub package uses inline types.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/__init__.py
new file mode 100644
index 000000000000..80fc23d59644
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/__init__.py
@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from .services.publisher import PublisherClient
+from .services.publisher import PublisherAsyncClient
+from .services.schema_service import SchemaServiceClient
+from .services.schema_service import SchemaServiceAsyncClient
+from .services.subscriber import SubscriberClient
+from .services.subscriber import SubscriberAsyncClient
+
+from .types.pubsub import AcknowledgeRequest
+from .types.pubsub import BigQueryConfig
+from .types.pubsub import CreateSnapshotRequest
+from .types.pubsub import DeadLetterPolicy
+from .types.pubsub import DeleteSnapshotRequest
+from .types.pubsub import DeleteSubscriptionRequest
+from .types.pubsub import DeleteTopicRequest
+from .types.pubsub import DetachSubscriptionRequest
+from .types.pubsub import DetachSubscriptionResponse
+from .types.pubsub import ExpirationPolicy
+from .types.pubsub import GetSnapshotRequest
+from .types.pubsub import GetSubscriptionRequest
+from .types.pubsub import GetTopicRequest
+from .types.pubsub import ListSnapshotsRequest
+from .types.pubsub import ListSnapshotsResponse
+from .types.pubsub import ListSubscriptionsRequest
+from .types.pubsub import ListSubscriptionsResponse
+from .types.pubsub import ListTopicSnapshotsRequest
+from .types.pubsub import ListTopicSnapshotsResponse
+from .types.pubsub import ListTopicsRequest
+from .types.pubsub import ListTopicsResponse
+from .types.pubsub import ListTopicSubscriptionsRequest
+from .types.pubsub import ListTopicSubscriptionsResponse
+from .types.pubsub import MessageStoragePolicy
+from .types.pubsub import ModifyAckDeadlineRequest
+from .types.pubsub import ModifyPushConfigRequest
+from .types.pubsub import PublishRequest
+from .types.pubsub import PublishResponse
+from .types.pubsub import PubsubMessage
+from .types.pubsub import PullRequest
+from .types.pubsub import PullResponse
+from .types.pubsub import PushConfig
+from .types.pubsub import ReceivedMessage
+from .types.pubsub import RetryPolicy
+from .types.pubsub import SchemaSettings
+from .types.pubsub import SeekRequest
+from .types.pubsub import SeekResponse
+from .types.pubsub import Snapshot
+from .types.pubsub import StreamingPullRequest
+from .types.pubsub import StreamingPullResponse
+from .types.pubsub import Subscription
+from .types.pubsub import Topic
+from .types.pubsub import UpdateSnapshotRequest
+from .types.pubsub import UpdateSubscriptionRequest
+from .types.pubsub import UpdateTopicRequest
+from .types.schema import CreateSchemaRequest
+from .types.schema import DeleteSchemaRequest
+from .types.schema import GetSchemaRequest
+from .types.schema import ListSchemasRequest
+from .types.schema import ListSchemasResponse
+from .types.schema import Schema
+from .types.schema import ValidateMessageRequest
+from .types.schema import ValidateMessageResponse
+from .types.schema import ValidateSchemaRequest
+from .types.schema import ValidateSchemaResponse
+from .types.schema import Encoding
+from .types.schema import SchemaView
+
+__all__ = (
+ "PublisherAsyncClient",
+ "SchemaServiceAsyncClient",
+ "SubscriberAsyncClient",
+ "AcknowledgeRequest",
+ "BigQueryConfig",
+ "CreateSchemaRequest",
+ "CreateSnapshotRequest",
+ "DeadLetterPolicy",
+ "DeleteSchemaRequest",
+ "DeleteSnapshotRequest",
+ "DeleteSubscriptionRequest",
+ "DeleteTopicRequest",
+ "DetachSubscriptionRequest",
+ "DetachSubscriptionResponse",
+ "Encoding",
+ "ExpirationPolicy",
+ "GetSchemaRequest",
+ "GetSnapshotRequest",
+ "GetSubscriptionRequest",
+ "GetTopicRequest",
+ "ListSchemasRequest",
+ "ListSchemasResponse",
+ "ListSnapshotsRequest",
+ "ListSnapshotsResponse",
+ "ListSubscriptionsRequest",
+ "ListSubscriptionsResponse",
+ "ListTopicSnapshotsRequest",
+ "ListTopicSnapshotsResponse",
+ "ListTopicSubscriptionsRequest",
+ "ListTopicSubscriptionsResponse",
+ "ListTopicsRequest",
+ "ListTopicsResponse",
+ "MessageStoragePolicy",
+ "ModifyAckDeadlineRequest",
+ "ModifyPushConfigRequest",
+ "PublishRequest",
+ "PublishResponse",
+ "PublisherClient",
+ "PubsubMessage",
+ "PullRequest",
+ "PullResponse",
+ "PushConfig",
+ "ReceivedMessage",
+ "RetryPolicy",
+ "Schema",
+ "SchemaServiceClient",
+ "SchemaSettings",
+ "SchemaView",
+ "SeekRequest",
+ "SeekResponse",
+ "Snapshot",
+ "StreamingPullRequest",
+ "StreamingPullResponse",
+ "SubscriberClient",
+ "Subscription",
+ "Topic",
+ "UpdateSnapshotRequest",
+ "UpdateSubscriptionRequest",
+ "UpdateTopicRequest",
+ "ValidateMessageRequest",
+ "ValidateMessageResponse",
+ "ValidateSchemaRequest",
+ "ValidateSchemaResponse",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/gapic_metadata.json b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/gapic_metadata.json
new file mode 100644
index 000000000000..4c5b86bd13bc
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/gapic_metadata.json
@@ -0,0 +1,361 @@
+ {
+ "comment": "This file maps proto services/RPCs to the corresponding library clients/methods",
+ "language": "python",
+ "libraryPackage": "google.pubsub_v1",
+ "protoPackage": "google.pubsub.v1",
+ "schema": "1.0",
+ "services": {
+ "Publisher": {
+ "clients": {
+ "grpc": {
+ "libraryClient": "PublisherClient",
+ "rpcs": {
+ "CreateTopic": {
+ "methods": [
+ "create_topic"
+ ]
+ },
+ "DeleteTopic": {
+ "methods": [
+ "delete_topic"
+ ]
+ },
+ "DetachSubscription": {
+ "methods": [
+ "detach_subscription"
+ ]
+ },
+ "GetTopic": {
+ "methods": [
+ "get_topic"
+ ]
+ },
+ "ListTopicSnapshots": {
+ "methods": [
+ "list_topic_snapshots"
+ ]
+ },
+ "ListTopicSubscriptions": {
+ "methods": [
+ "list_topic_subscriptions"
+ ]
+ },
+ "ListTopics": {
+ "methods": [
+ "list_topics"
+ ]
+ },
+ "Publish": {
+ "methods": [
+ "publish"
+ ]
+ },
+ "UpdateTopic": {
+ "methods": [
+ "update_topic"
+ ]
+ }
+ }
+ },
+ "grpc-async": {
+ "libraryClient": "PublisherAsyncClient",
+ "rpcs": {
+ "CreateTopic": {
+ "methods": [
+ "create_topic"
+ ]
+ },
+ "DeleteTopic": {
+ "methods": [
+ "delete_topic"
+ ]
+ },
+ "DetachSubscription": {
+ "methods": [
+ "detach_subscription"
+ ]
+ },
+ "GetTopic": {
+ "methods": [
+ "get_topic"
+ ]
+ },
+ "ListTopicSnapshots": {
+ "methods": [
+ "list_topic_snapshots"
+ ]
+ },
+ "ListTopicSubscriptions": {
+ "methods": [
+ "list_topic_subscriptions"
+ ]
+ },
+ "ListTopics": {
+ "methods": [
+ "list_topics"
+ ]
+ },
+ "Publish": {
+ "methods": [
+ "publish"
+ ]
+ },
+ "UpdateTopic": {
+ "methods": [
+ "update_topic"
+ ]
+ }
+ }
+ }
+ }
+ },
+ "SchemaService": {
+ "clients": {
+ "grpc": {
+ "libraryClient": "SchemaServiceClient",
+ "rpcs": {
+ "CreateSchema": {
+ "methods": [
+ "create_schema"
+ ]
+ },
+ "DeleteSchema": {
+ "methods": [
+ "delete_schema"
+ ]
+ },
+ "GetSchema": {
+ "methods": [
+ "get_schema"
+ ]
+ },
+ "ListSchemas": {
+ "methods": [
+ "list_schemas"
+ ]
+ },
+ "ValidateMessage": {
+ "methods": [
+ "validate_message"
+ ]
+ },
+ "ValidateSchema": {
+ "methods": [
+ "validate_schema"
+ ]
+ }
+ }
+ },
+ "grpc-async": {
+ "libraryClient": "SchemaServiceAsyncClient",
+ "rpcs": {
+ "CreateSchema": {
+ "methods": [
+ "create_schema"
+ ]
+ },
+ "DeleteSchema": {
+ "methods": [
+ "delete_schema"
+ ]
+ },
+ "GetSchema": {
+ "methods": [
+ "get_schema"
+ ]
+ },
+ "ListSchemas": {
+ "methods": [
+ "list_schemas"
+ ]
+ },
+ "ValidateMessage": {
+ "methods": [
+ "validate_message"
+ ]
+ },
+ "ValidateSchema": {
+ "methods": [
+ "validate_schema"
+ ]
+ }
+ }
+ }
+ }
+ },
+ "Subscriber": {
+ "clients": {
+ "grpc": {
+ "libraryClient": "SubscriberClient",
+ "rpcs": {
+ "Acknowledge": {
+ "methods": [
+ "acknowledge"
+ ]
+ },
+ "CreateSnapshot": {
+ "methods": [
+ "create_snapshot"
+ ]
+ },
+ "CreateSubscription": {
+ "methods": [
+ "create_subscription"
+ ]
+ },
+ "DeleteSnapshot": {
+ "methods": [
+ "delete_snapshot"
+ ]
+ },
+ "DeleteSubscription": {
+ "methods": [
+ "delete_subscription"
+ ]
+ },
+ "GetSnapshot": {
+ "methods": [
+ "get_snapshot"
+ ]
+ },
+ "GetSubscription": {
+ "methods": [
+ "get_subscription"
+ ]
+ },
+ "ListSnapshots": {
+ "methods": [
+ "list_snapshots"
+ ]
+ },
+ "ListSubscriptions": {
+ "methods": [
+ "list_subscriptions"
+ ]
+ },
+ "ModifyAckDeadline": {
+ "methods": [
+ "modify_ack_deadline"
+ ]
+ },
+ "ModifyPushConfig": {
+ "methods": [
+ "modify_push_config"
+ ]
+ },
+ "Pull": {
+ "methods": [
+ "pull"
+ ]
+ },
+ "Seek": {
+ "methods": [
+ "seek"
+ ]
+ },
+ "StreamingPull": {
+ "methods": [
+ "streaming_pull"
+ ]
+ },
+ "UpdateSnapshot": {
+ "methods": [
+ "update_snapshot"
+ ]
+ },
+ "UpdateSubscription": {
+ "methods": [
+ "update_subscription"
+ ]
+ }
+ }
+ },
+ "grpc-async": {
+ "libraryClient": "SubscriberAsyncClient",
+ "rpcs": {
+ "Acknowledge": {
+ "methods": [
+ "acknowledge"
+ ]
+ },
+ "CreateSnapshot": {
+ "methods": [
+ "create_snapshot"
+ ]
+ },
+ "CreateSubscription": {
+ "methods": [
+ "create_subscription"
+ ]
+ },
+ "DeleteSnapshot": {
+ "methods": [
+ "delete_snapshot"
+ ]
+ },
+ "DeleteSubscription": {
+ "methods": [
+ "delete_subscription"
+ ]
+ },
+ "GetSnapshot": {
+ "methods": [
+ "get_snapshot"
+ ]
+ },
+ "GetSubscription": {
+ "methods": [
+ "get_subscription"
+ ]
+ },
+ "ListSnapshots": {
+ "methods": [
+ "list_snapshots"
+ ]
+ },
+ "ListSubscriptions": {
+ "methods": [
+ "list_subscriptions"
+ ]
+ },
+ "ModifyAckDeadline": {
+ "methods": [
+ "modify_ack_deadline"
+ ]
+ },
+ "ModifyPushConfig": {
+ "methods": [
+ "modify_push_config"
+ ]
+ },
+ "Pull": {
+ "methods": [
+ "pull"
+ ]
+ },
+ "Seek": {
+ "methods": [
+ "seek"
+ ]
+ },
+ "StreamingPull": {
+ "methods": [
+ "streaming_pull"
+ ]
+ },
+ "UpdateSnapshot": {
+ "methods": [
+ "update_snapshot"
+ ]
+ },
+ "UpdateSubscription": {
+ "methods": [
+ "update_subscription"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/py.typed b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/py.typed
new file mode 100644
index 000000000000..1cec9a5ba1ab
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/py.typed
@@ -0,0 +1,2 @@
+# Marker file for PEP 561.
+# The google-cloud-pubsub package uses inline types.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/__init__.py
new file mode 100644
index 000000000000..e8e1c3845db5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/__init__.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/__init__.py
new file mode 100644
index 000000000000..56fb64a17a88
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from .client import PublisherClient
+from .async_client import PublisherAsyncClient
+
+__all__ = (
+ "PublisherClient",
+ "PublisherAsyncClient",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/async_client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/async_client.py
new file mode 100644
index 000000000000..dbcd516b2ba9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/async_client.py
@@ -0,0 +1,1561 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import functools
+import re
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
+import pkg_resources
+
+from google.api_core.client_options import ClientOptions
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.api_core import timeout as timeouts # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import duration_pb2 # type: ignore
+from google.pubsub_v1.services.publisher import pagers
+from google.pubsub_v1.types import pubsub
+from google.pubsub_v1.types import TimeoutType
+from .transports.base import PublisherTransport, DEFAULT_CLIENT_INFO
+from .transports.grpc_asyncio import PublisherGrpcAsyncIOTransport
+from .client import PublisherClient
+
+
+class PublisherAsyncClient:
+ """The service that an application uses to manipulate topics,
+ and to send messages to a topic.
+ """
+
+ _client: PublisherClient
+
+ DEFAULT_ENDPOINT = PublisherClient.DEFAULT_ENDPOINT
+ DEFAULT_MTLS_ENDPOINT = PublisherClient.DEFAULT_MTLS_ENDPOINT
+
+ schema_path = staticmethod(PublisherClient.schema_path)
+ parse_schema_path = staticmethod(PublisherClient.parse_schema_path)
+ subscription_path = staticmethod(PublisherClient.subscription_path)
+ parse_subscription_path = staticmethod(PublisherClient.parse_subscription_path)
+ topic_path = staticmethod(PublisherClient.topic_path)
+ parse_topic_path = staticmethod(PublisherClient.parse_topic_path)
+ common_billing_account_path = staticmethod(
+ PublisherClient.common_billing_account_path
+ )
+ parse_common_billing_account_path = staticmethod(
+ PublisherClient.parse_common_billing_account_path
+ )
+ common_folder_path = staticmethod(PublisherClient.common_folder_path)
+ parse_common_folder_path = staticmethod(PublisherClient.parse_common_folder_path)
+ common_organization_path = staticmethod(PublisherClient.common_organization_path)
+ parse_common_organization_path = staticmethod(
+ PublisherClient.parse_common_organization_path
+ )
+ common_project_path = staticmethod(PublisherClient.common_project_path)
+ parse_common_project_path = staticmethod(PublisherClient.parse_common_project_path)
+ common_location_path = staticmethod(PublisherClient.common_location_path)
+ parse_common_location_path = staticmethod(
+ PublisherClient.parse_common_location_path
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ PublisherAsyncClient: The constructed client.
+ """
+ return PublisherClient.from_service_account_info.__func__(PublisherAsyncClient, info, *args, **kwargs) # type: ignore
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ PublisherAsyncClient: The constructed client.
+ """
+ return PublisherClient.from_service_account_file.__func__(PublisherAsyncClient, filename, *args, **kwargs) # type: ignore
+
+ from_service_account_json = from_service_account_file
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ return PublisherClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore
+
+ @property
+ def transport(self) -> PublisherTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ PublisherTransport: The transport used by the client instance.
+ """
+ return self._client.transport
+
+ get_transport_class = functools.partial(
+ type(PublisherClient).get_transport_class, type(PublisherClient)
+ )
+
+ def __init__(
+ self,
+ *,
+ credentials: ga_credentials.Credentials = None,
+ transport: Union[str, PublisherTransport] = "grpc_asyncio",
+ client_options: ClientOptions = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the publisher client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, ~.PublisherTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (ClientOptions): Custom options for the client. It
+ won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ self._client = PublisherClient(
+ credentials=credentials,
+ transport=transport,
+ client_options=client_options,
+ client_info=client_info,
+ )
+
+ async def create_topic(
+ self,
+ request: Union[pubsub.Topic, dict] = None,
+ *,
+ name: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Topic:
+ r"""Creates the given topic with the given name. See the [resource
+ name rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names).
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_create_topic():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.Topic(
+ name="name_value",
+ )
+
+ # Make the request
+ response = await client.create_topic(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.Topic, dict]):
+ The request object. A topic resource.
+ name (:class:`str`):
+ Required. The name of the topic. It must have the format
+ ``"projects/{project}/topics/{topic}"``. ``{topic}``
+ must start with a letter, and contain only letters
+ (``[A-Za-z]``), numbers (``[0-9]``), dashes (``-``),
+ underscores (``_``), periods (``.``), tildes (``~``),
+ plus (``+``) or percent signs (``%``). It must be
+ between 3 and 255 characters in length, and it must not
+ start with ``"goog"``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Topic:
+ A topic resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.Topic(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.create_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def update_topic(
+ self,
+ request: Union[pubsub.UpdateTopicRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Topic:
+ r"""Updates an existing topic. Note that certain
+ properties of a topic are not modifiable.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_update_topic():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ topic = pubsub_v1.Topic()
+ topic.name = "name_value"
+
+ request = pubsub_v1.UpdateTopicRequest(
+ topic=topic,
+ )
+
+ # Make the request
+ response = await client.update_topic(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.UpdateTopicRequest, dict]):
+ The request object. Request for the UpdateTopic method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Topic:
+ A topic resource.
+ """
+ # Create or coerce a protobuf request object.
+ request = pubsub.UpdateTopicRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.update_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("topic.name", request.topic.name),)
+ ),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def publish(
+ self,
+ request: Union[pubsub.PublishRequest, dict] = None,
+ *,
+ topic: str = None,
+ messages: Sequence[pubsub.PubsubMessage] = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.PublishResponse:
+ r"""Adds one or more messages to the topic. Returns ``NOT_FOUND`` if
+ the topic does not exist.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_publish():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.PublishRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ response = await client.publish(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.PublishRequest, dict]):
+ The request object. Request for the Publish method.
+ topic (:class:`str`):
+ Required. The messages in the request will be published
+ on this topic. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ messages (:class:`Sequence[google.pubsub_v1.types.PubsubMessage]`):
+ Required. The messages to publish.
+ This corresponds to the ``messages`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.PublishResponse:
+ Response for the Publish method.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic, messages])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.PublishRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+ if messages:
+ request.messages.extend(messages)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.publish,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.Cancelled,
+ core_exceptions.DeadlineExceeded,
+ core_exceptions.InternalServerError,
+ core_exceptions.ResourceExhausted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def get_topic(
+ self,
+ request: Union[pubsub.GetTopicRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Topic:
+ r"""Gets the configuration of a topic.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_get_topic():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetTopicRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ response = await client.get_topic(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetTopicRequest, dict]):
+ The request object. Request for the GetTopic method.
+ topic (:class:`str`):
+ Required. The name of the topic to get. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Topic:
+ A topic resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.GetTopicRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.get_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def list_topics(
+ self,
+ request: Union[pubsub.ListTopicsRequest, dict] = None,
+ *,
+ project: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicsAsyncPager:
+ r"""Lists matching topics.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_list_topics():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListTopicsRequest(
+ project="project_value",
+ )
+
+ # Make the request
+ page_result = client.list_topics(request=request)
+
+ # Handle the response
+ async for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListTopicsRequest, dict]):
+ The request object. Request for the `ListTopics` method.
+ project (:class:`str`):
+ Required. The name of the project in which to list
+ topics. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``project`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager:
+ Response for the ListTopics method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([project])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.ListTopicsRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if project is not None:
+ request.project = project
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_topics,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__aiter__` convenience method.
+ response = pagers.ListTopicsAsyncPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def list_topic_subscriptions(
+ self,
+ request: Union[pubsub.ListTopicSubscriptionsRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicSubscriptionsAsyncPager:
+ r"""Lists the names of the attached subscriptions on this
+ topic.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_list_topic_subscriptions():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListTopicSubscriptionsRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ page_result = client.list_topic_subscriptions(request=request)
+
+ # Handle the response
+ async for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListTopicSubscriptionsRequest, dict]):
+ The request object. Request for the
+ `ListTopicSubscriptions` method.
+ topic (:class:`str`):
+ Required. The name of the topic that subscriptions are
+ attached to. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager:
+ Response for the ListTopicSubscriptions method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.ListTopicSubscriptionsRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_topic_subscriptions,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__aiter__` convenience method.
+ response = pagers.ListTopicSubscriptionsAsyncPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def list_topic_snapshots(
+ self,
+ request: Union[pubsub.ListTopicSnapshotsRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicSnapshotsAsyncPager:
+ r"""Lists the names of the snapshots on this topic. Snapshots are
+ used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_list_topic_snapshots():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListTopicSnapshotsRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ page_result = client.list_topic_snapshots(request=request)
+
+ # Handle the response
+ async for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListTopicSnapshotsRequest, dict]):
+ The request object. Request for the `ListTopicSnapshots`
+ method.
+ topic (:class:`str`):
+ Required. The name of the topic that snapshots are
+ attached to. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager:
+ Response for the ListTopicSnapshots method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.ListTopicSnapshotsRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_topic_snapshots,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__aiter__` convenience method.
+ response = pagers.ListTopicSnapshotsAsyncPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def delete_topic(
+ self,
+ request: Union[pubsub.DeleteTopicRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Deletes the topic with the given name. Returns ``NOT_FOUND`` if
+ the topic does not exist. After a topic is deleted, a new topic
+ may be created with the same name; this is an entirely new topic
+ with none of the old configuration or subscriptions. Existing
+ subscriptions to this topic are not deleted, but their ``topic``
+ field is set to ``_deleted-topic_``.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_delete_topic():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteTopicRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ await client.delete_topic(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteTopicRequest, dict]):
+ The request object. Request for the `DeleteTopic`
+ method.
+ topic (:class:`str`):
+ Required. Name of the topic to delete. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.DeleteTopicRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.delete_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ async def detach_subscription(
+ self,
+ request: Union[pubsub.DetachSubscriptionRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.DetachSubscriptionResponse:
+ r"""Detaches a subscription from this topic. All messages retained
+ in the subscription are dropped. Subsequent ``Pull`` and
+ ``StreamingPull`` requests will return FAILED_PRECONDITION. If
+ the subscription is a push subscription, pushes to the endpoint
+ will stop.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_detach_subscription():
+ # Create a client
+ client = pubsub_v1.PublisherAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DetachSubscriptionRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = await client.detach_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DetachSubscriptionRequest, dict]):
+ The request object. Request for the DetachSubscription
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.DetachSubscriptionResponse:
+ Response for the DetachSubscription
+ method. Reserved for future use.
+
+ """
+ # Create or coerce a protobuf request object.
+ request = pubsub.DetachSubscriptionRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.detach_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def set_iam_policy(
+ self,
+ request: iam_policy_pb2.SetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Sets the IAM access control policy on the specified function.
+
+ Replaces any existing policy.
+
+ Args:
+ request (:class:`~.policy_pb2.SetIamPolicyRequest`):
+ The request object. Request message for `SetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.SetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.set_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def get_iam_policy(
+ self,
+ request: iam_policy_pb2.GetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Gets the IAM access control policy for a function.
+
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.GetIamPolicyRequest`):
+ The request object. Request message for `GetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.GetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.get_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def test_iam_permissions(
+ self,
+ request: iam_policy_pb2.TestIamPermissionsRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> iam_policy_pb2.TestIamPermissionsResponse:
+ r"""Tests the specified permissions against the IAM access control
+ policy for a function.
+
+ If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.TestIamPermissionsRequest`):
+ The request object. Request message for
+ `TestIamPermissions` method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~iam_policy_pb2.PolicyTestIamPermissionsResponse:
+ Response message for ``TestIamPermissions`` method.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.TestIamPermissionsRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.test_iam_permissions,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb):
+ await self.transport.close()
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("PublisherAsyncClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
new file mode 100644
index 000000000000..f8a640422f8d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
@@ -0,0 +1,1754 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import functools
+import os
+import re
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
+import pkg_resources
+
+from google.api_core import client_options as client_options_lib
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.api_core import timeout as timeouts # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport import mtls # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+from google.auth.exceptions import MutualTLSChannelError # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import duration_pb2 # type: ignore
+from google.pubsub_v1.services.publisher import pagers
+from google.pubsub_v1.types import pubsub
+from google.pubsub_v1.types import TimeoutType
+
+import grpc
+from .transports.base import PublisherTransport, DEFAULT_CLIENT_INFO
+from .transports.grpc import PublisherGrpcTransport
+from .transports.grpc_asyncio import PublisherGrpcAsyncIOTransport
+
+
+class PublisherClientMeta(type):
+ """Metaclass for the Publisher client.
+
+ This provides class-level methods for building and retrieving
+ support objects (e.g. transport) without polluting the client instance
+ objects.
+ """
+
+ _transport_registry = OrderedDict() # type: Dict[str, Type[PublisherTransport]]
+ _transport_registry["grpc"] = PublisherGrpcTransport
+ _transport_registry["grpc_asyncio"] = PublisherGrpcAsyncIOTransport
+
+ def get_transport_class(
+ cls,
+ label: str = None,
+ ) -> Type[PublisherTransport]:
+ """Returns an appropriate transport class.
+
+ Args:
+ label: The name of the desired transport. If none is
+ provided, then the first transport in the registry is used.
+
+ Returns:
+ The transport class to use.
+ """
+ # If a specific transport is requested, return that one.
+ if label:
+ return cls._transport_registry[label]
+
+ # No transport is requested; return the default (that is, the first one
+ # in the dictionary).
+ return next(iter(cls._transport_registry.values()))
+
+
+class PublisherClient(metaclass=PublisherClientMeta):
+ """The service that an application uses to manipulate topics,
+ and to send messages to a topic.
+ """
+
+ @staticmethod
+ def _get_default_mtls_endpoint(api_endpoint):
+ """Converts api endpoint to mTLS endpoint.
+
+ Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
+ "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
+ Args:
+ api_endpoint (Optional[str]): the api endpoint to convert.
+ Returns:
+ str: converted mTLS api endpoint.
+ """
+ if not api_endpoint:
+ return api_endpoint
+
+ mtls_endpoint_re = re.compile(
+ r"(?P[^.]+)(?P\.mtls)?(?P\.sandbox)?(?P\.googleapis\.com)?"
+ )
+
+ m = mtls_endpoint_re.match(api_endpoint)
+ name, mtls, sandbox, googledomain = m.groups()
+ if mtls or not googledomain:
+ return api_endpoint
+
+ if sandbox:
+ return api_endpoint.replace(
+ "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
+ )
+
+ return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
+
+ # The scopes needed to make gRPC calls to all of the methods defined in
+ # this service
+ _DEFAULT_SCOPES = (
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/pubsub",
+ )
+
+ SERVICE_ADDRESS = "pubsub.googleapis.com:443"
+ """The default address of the service."""
+
+ DEFAULT_ENDPOINT = "pubsub.googleapis.com"
+ DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore
+ DEFAULT_ENDPOINT
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ PublisherClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_info(info)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ PublisherClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_file(filename)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ from_service_account_json = from_service_account_file
+
+ @property
+ def transport(self) -> PublisherTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ PublisherTransport: The transport used by the client
+ instance.
+ """
+ return self._transport
+
+ @staticmethod
+ def schema_path(
+ project: str,
+ schema: str,
+ ) -> str:
+ """Returns a fully-qualified schema string."""
+ return "projects/{project}/schemas/{schema}".format(
+ project=project,
+ schema=schema,
+ )
+
+ @staticmethod
+ def parse_schema_path(path: str) -> Dict[str, str]:
+ """Parses a schema path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/schemas/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def subscription_path(
+ project: str,
+ subscription: str,
+ ) -> str:
+ """Returns a fully-qualified subscription string."""
+ return "projects/{project}/subscriptions/{subscription}".format(
+ project=project,
+ subscription=subscription,
+ )
+
+ @staticmethod
+ def parse_subscription_path(path: str) -> Dict[str, str]:
+ """Parses a subscription path into its component segments."""
+ m = re.match(
+ r"^projects/(?P.+?)/subscriptions/(?P.+?)$", path
+ )
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def topic_path(
+ project: str,
+ topic: str,
+ ) -> str:
+ """Returns a fully-qualified topic string."""
+ return "projects/{project}/topics/{topic}".format(
+ project=project,
+ topic=topic,
+ )
+
+ @staticmethod
+ def parse_topic_path(path: str) -> Dict[str, str]:
+ """Parses a topic path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/topics/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_billing_account_path(
+ billing_account: str,
+ ) -> str:
+ """Returns a fully-qualified billing_account string."""
+ return "billingAccounts/{billing_account}".format(
+ billing_account=billing_account,
+ )
+
+ @staticmethod
+ def parse_common_billing_account_path(path: str) -> Dict[str, str]:
+ """Parse a billing_account path into its component segments."""
+ m = re.match(r"^billingAccounts/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_folder_path(
+ folder: str,
+ ) -> str:
+ """Returns a fully-qualified folder string."""
+ return "folders/{folder}".format(
+ folder=folder,
+ )
+
+ @staticmethod
+ def parse_common_folder_path(path: str) -> Dict[str, str]:
+ """Parse a folder path into its component segments."""
+ m = re.match(r"^folders/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_organization_path(
+ organization: str,
+ ) -> str:
+ """Returns a fully-qualified organization string."""
+ return "organizations/{organization}".format(
+ organization=organization,
+ )
+
+ @staticmethod
+ def parse_common_organization_path(path: str) -> Dict[str, str]:
+ """Parse a organization path into its component segments."""
+ m = re.match(r"^organizations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_project_path(
+ project: str,
+ ) -> str:
+ """Returns a fully-qualified project string."""
+ return "projects/{project}".format(
+ project=project,
+ )
+
+ @staticmethod
+ def parse_common_project_path(path: str) -> Dict[str, str]:
+ """Parse a project path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_location_path(
+ project: str,
+ location: str,
+ ) -> str:
+ """Returns a fully-qualified location string."""
+ return "projects/{project}/locations/{location}".format(
+ project=project,
+ location=location,
+ )
+
+ @staticmethod
+ def parse_common_location_path(path: str) -> Dict[str, str]:
+ """Parse a location path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/locations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[client_options_lib.ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+ use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
+ use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
+ if use_client_cert not in ("true", "false"):
+ raise ValueError(
+ "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"
+ )
+ if use_mtls_endpoint not in ("auto", "never", "always"):
+ raise MutualTLSChannelError(
+ "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"
+ )
+
+ # Figure out the client cert source to use.
+ client_cert_source = None
+ if use_client_cert == "true":
+ if client_options.client_cert_source:
+ client_cert_source = client_options.client_cert_source
+ elif mtls.has_default_client_cert_source():
+ client_cert_source = mtls.default_client_cert_source()
+
+ # Figure out which api endpoint to use.
+ if client_options.api_endpoint is not None:
+ api_endpoint = client_options.api_endpoint
+ elif use_mtls_endpoint == "always" or (
+ use_mtls_endpoint == "auto" and client_cert_source
+ ):
+ api_endpoint = cls.DEFAULT_MTLS_ENDPOINT
+ else:
+ api_endpoint = cls.DEFAULT_ENDPOINT
+
+ return api_endpoint, client_cert_source
+
+ def __init__(
+ self,
+ *,
+ credentials: Optional[ga_credentials.Credentials] = None,
+ transport: Union[str, PublisherTransport, None] = None,
+ client_options: Optional[client_options_lib.ClientOptions] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the publisher client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, PublisherTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. It won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ if isinstance(client_options, dict):
+ client_options = client_options_lib.from_dict(client_options)
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+
+ api_endpoint, client_cert_source_func = self.get_mtls_endpoint_and_cert_source(
+ client_options
+ )
+
+ api_key_value = getattr(client_options, "api_key", None)
+ if api_key_value and credentials:
+ raise ValueError(
+ "client_options.api_key and credentials are mutually exclusive"
+ )
+
+ # Save or instantiate the transport.
+ # Ordinarily, we provide the transport, but allowing a custom transport
+ # instance provides an extensibility point for unusual situations.
+ if isinstance(transport, PublisherTransport):
+ # transport is a PublisherTransport instance.
+ if credentials or client_options.credentials_file or api_key_value:
+ raise ValueError(
+ "When providing a transport instance, "
+ "provide its credentials directly."
+ )
+ if client_options.scopes:
+ raise ValueError(
+ "When providing a transport instance, provide its scopes "
+ "directly."
+ )
+ self._transport = transport
+ else:
+ import google.auth._default # type: ignore
+
+ if api_key_value and hasattr(
+ google.auth._default, "get_api_key_credentials"
+ ):
+ credentials = google.auth._default.get_api_key_credentials(
+ api_key_value
+ )
+
+ Transport = type(self).get_transport_class(transport)
+
+ emulator_host = os.environ.get("PUBSUB_EMULATOR_HOST")
+ if emulator_host:
+ if issubclass(Transport, type(self)._transport_registry["grpc"]):
+ channel = grpc.insecure_channel(target=emulator_host)
+ else:
+ channel = grpc.aio.insecure_channel(target=emulator_host)
+ Transport = functools.partial(Transport, channel=channel)
+
+ self._transport = Transport(
+ credentials=credentials,
+ credentials_file=client_options.credentials_file,
+ host=api_endpoint,
+ scopes=client_options.scopes,
+ client_cert_source_for_mtls=client_cert_source_func,
+ quota_project_id=client_options.quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=True,
+ api_audience=client_options.api_audience,
+ )
+
+ def create_topic(
+ self,
+ request: Union[pubsub.Topic, dict] = None,
+ *,
+ name: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Topic:
+ r"""Creates the given topic with the given name. See the [resource
+ name rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names).
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_create_topic():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.Topic(
+ name="name_value",
+ )
+
+ # Make the request
+ response = client.create_topic(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.Topic, dict]):
+ The request object. A topic resource.
+ name (str):
+ Required. The name of the topic. It must have the format
+ ``"projects/{project}/topics/{topic}"``. ``{topic}``
+ must start with a letter, and contain only letters
+ (``[A-Za-z]``), numbers (``[0-9]``), dashes (``-``),
+ underscores (``_``), periods (``.``), tildes (``~``),
+ plus (``+``) or percent signs (``%``). It must be
+ between 3 and 255 characters in length, and it must not
+ start with ``"goog"``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Topic:
+ A topic resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.Topic.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.Topic):
+ request = pubsub.Topic(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.create_topic]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def update_topic(
+ self,
+ request: Union[pubsub.UpdateTopicRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Topic:
+ r"""Updates an existing topic. Note that certain
+ properties of a topic are not modifiable.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_update_topic():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ topic = pubsub_v1.Topic()
+ topic.name = "name_value"
+
+ request = pubsub_v1.UpdateTopicRequest(
+ topic=topic,
+ )
+
+ # Make the request
+ response = client.update_topic(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.UpdateTopicRequest, dict]):
+ The request object. Request for the UpdateTopic method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Topic:
+ A topic resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.UpdateTopicRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.UpdateTopicRequest):
+ request = pubsub.UpdateTopicRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.update_topic]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("topic.name", request.topic.name),)
+ ),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def publish(
+ self,
+ request: Union[pubsub.PublishRequest, dict] = None,
+ *,
+ topic: str = None,
+ messages: Sequence[pubsub.PubsubMessage] = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.PublishResponse:
+ r"""Adds one or more messages to the topic. Returns ``NOT_FOUND`` if
+ the topic does not exist.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_publish():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.PublishRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ response = client.publish(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.PublishRequest, dict]):
+ The request object. Request for the Publish method.
+ topic (str):
+ Required. The messages in the request will be published
+ on this topic. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ messages (Sequence[google.pubsub_v1.types.PubsubMessage]):
+ Required. The messages to publish.
+ This corresponds to the ``messages`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.PublishResponse:
+ Response for the Publish method.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic, messages])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.PublishRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.PublishRequest):
+ request = pubsub.PublishRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+ if messages is not None:
+ request.messages = messages
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.publish]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def get_topic(
+ self,
+ request: Union[pubsub.GetTopicRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Topic:
+ r"""Gets the configuration of a topic.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_get_topic():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetTopicRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ response = client.get_topic(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetTopicRequest, dict]):
+ The request object. Request for the GetTopic method.
+ topic (str):
+ Required. The name of the topic to get. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Topic:
+ A topic resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.GetTopicRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.GetTopicRequest):
+ request = pubsub.GetTopicRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.get_topic]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def list_topics(
+ self,
+ request: Union[pubsub.ListTopicsRequest, dict] = None,
+ *,
+ project: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicsPager:
+ r"""Lists matching topics.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_list_topics():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListTopicsRequest(
+ project="project_value",
+ )
+
+ # Make the request
+ page_result = client.list_topics(request=request)
+
+ # Handle the response
+ for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListTopicsRequest, dict]):
+ The request object. Request for the `ListTopics` method.
+ project (str):
+ Required. The name of the project in which to list
+ topics. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``project`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.publisher.pagers.ListTopicsPager:
+ Response for the ListTopics method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([project])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.ListTopicsRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.ListTopicsRequest):
+ request = pubsub.ListTopicsRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if project is not None:
+ request.project = project
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_topics]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__iter__` convenience method.
+ response = pagers.ListTopicsPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def list_topic_subscriptions(
+ self,
+ request: Union[pubsub.ListTopicSubscriptionsRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicSubscriptionsPager:
+ r"""Lists the names of the attached subscriptions on this
+ topic.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_list_topic_subscriptions():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListTopicSubscriptionsRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ page_result = client.list_topic_subscriptions(request=request)
+
+ # Handle the response
+ for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListTopicSubscriptionsRequest, dict]):
+ The request object. Request for the
+ `ListTopicSubscriptions` method.
+ topic (str):
+ Required. The name of the topic that subscriptions are
+ attached to. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager:
+ Response for the ListTopicSubscriptions method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.ListTopicSubscriptionsRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.ListTopicSubscriptionsRequest):
+ request = pubsub.ListTopicSubscriptionsRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_topic_subscriptions]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__iter__` convenience method.
+ response = pagers.ListTopicSubscriptionsPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def list_topic_snapshots(
+ self,
+ request: Union[pubsub.ListTopicSnapshotsRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicSnapshotsPager:
+ r"""Lists the names of the snapshots on this topic. Snapshots are
+ used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_list_topic_snapshots():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListTopicSnapshotsRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ page_result = client.list_topic_snapshots(request=request)
+
+ # Handle the response
+ for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListTopicSnapshotsRequest, dict]):
+ The request object. Request for the `ListTopicSnapshots`
+ method.
+ topic (str):
+ Required. The name of the topic that snapshots are
+ attached to. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager:
+ Response for the ListTopicSnapshots method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.ListTopicSnapshotsRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.ListTopicSnapshotsRequest):
+ request = pubsub.ListTopicSnapshotsRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_topic_snapshots]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__iter__` convenience method.
+ response = pagers.ListTopicSnapshotsPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def delete_topic(
+ self,
+ request: Union[pubsub.DeleteTopicRequest, dict] = None,
+ *,
+ topic: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Deletes the topic with the given name. Returns ``NOT_FOUND`` if
+ the topic does not exist. After a topic is deleted, a new topic
+ may be created with the same name; this is an entirely new topic
+ with none of the old configuration or subscriptions. Existing
+ subscriptions to this topic are not deleted, but their ``topic``
+ field is set to ``_deleted-topic_``.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_delete_topic():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteTopicRequest(
+ topic="topic_value",
+ )
+
+ # Make the request
+ client.delete_topic(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteTopicRequest, dict]):
+ The request object. Request for the `DeleteTopic`
+ method.
+ topic (str):
+ Required. Name of the topic to delete. Format is
+ ``projects/{project}/topics/{topic}``.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([topic])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.DeleteTopicRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.DeleteTopicRequest):
+ request = pubsub.DeleteTopicRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if topic is not None:
+ request.topic = topic
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.delete_topic]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("topic", request.topic),)),
+ )
+
+ # Send the request.
+ rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ def detach_subscription(
+ self,
+ request: Union[pubsub.DetachSubscriptionRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.DetachSubscriptionResponse:
+ r"""Detaches a subscription from this topic. All messages retained
+ in the subscription are dropped. Subsequent ``Pull`` and
+ ``StreamingPull`` requests will return FAILED_PRECONDITION. If
+ the subscription is a push subscription, pushes to the endpoint
+ will stop.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_detach_subscription():
+ # Create a client
+ client = pubsub_v1.PublisherClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DetachSubscriptionRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = client.detach_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DetachSubscriptionRequest, dict]):
+ The request object. Request for the DetachSubscription
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.DetachSubscriptionResponse:
+ Response for the DetachSubscription
+ method. Reserved for future use.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.DetachSubscriptionRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.DetachSubscriptionRequest):
+ request = pubsub.DetachSubscriptionRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.detach_subscription]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, type, value, traceback):
+ """Releases underlying transport's resources.
+
+ .. warning::
+ ONLY use as a context manager if the transport is NOT shared
+ with other clients! Exiting the with block will CLOSE the transport
+ and may cause errors in other clients!
+ """
+ self.transport.close()
+
+ def set_iam_policy(
+ self,
+ request: iam_policy_pb2.SetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Sets the IAM access control policy on the specified function.
+
+ Replaces any existing policy.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.SetIamPolicyRequest`):
+ The request object. Request message for `SetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.SetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.set_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def get_iam_policy(
+ self,
+ request: iam_policy_pb2.GetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Gets the IAM access control policy for a function.
+
+ Returns an empty policy if the function exists and does not have a
+ policy set.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.GetIamPolicyRequest`):
+ The request object. Request message for `GetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if
+ any, should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.GetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.get_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def test_iam_permissions(
+ self,
+ request: iam_policy_pb2.TestIamPermissionsRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> iam_policy_pb2.TestIamPermissionsResponse:
+ r"""Tests the specified IAM permissions against the IAM access control
+ policy for a function.
+
+ If the function does not exist, this will return an empty set
+ of permissions, not a NOT_FOUND error.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.TestIamPermissionsRequest`):
+ The request object. Request message for
+ `TestIamPermissions` method.
+ retry (google.api_core.retry.Retry): Designation of what errors,
+ if any, should be retried.
+ timeout (TimeoutType):
+ The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.iam_policy_pb2.TestIamPermissionsResponse:
+ Response message for ``TestIamPermissions`` method.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.TestIamPermissionsRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.test_iam_permissions,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("PublisherClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
new file mode 100644
index 000000000000..1e095181f7be
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
@@ -0,0 +1,411 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import (
+ Any,
+ AsyncIterator,
+ Awaitable,
+ Callable,
+ Sequence,
+ Tuple,
+ Optional,
+ Iterator,
+)
+
+from google.pubsub_v1.types import pubsub
+
+
+class ListTopicsPager:
+ """A pager for iterating through ``list_topics`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListTopicsResponse` object, and
+ provides an ``__iter__`` method to iterate through its
+ ``topics`` field.
+
+ If there are more pages, the ``__iter__`` method will make additional
+ ``ListTopics`` requests and continue to iterate
+ through the ``topics`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListTopicsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., pubsub.ListTopicsResponse],
+ request: pubsub.ListTopicsRequest,
+ response: pubsub.ListTopicsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiate the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListTopicsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListTopicsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListTopicsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ def pages(self) -> Iterator[pubsub.ListTopicsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __iter__(self) -> Iterator[pubsub.Topic]:
+ for page in self.pages:
+ yield from page.topics
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListTopicsAsyncPager:
+ """A pager for iterating through ``list_topics`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListTopicsResponse` object, and
+ provides an ``__aiter__`` method to iterate through its
+ ``topics`` field.
+
+ If there are more pages, the ``__aiter__`` method will make additional
+ ``ListTopics`` requests and continue to iterate
+ through the ``topics`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListTopicsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., Awaitable[pubsub.ListTopicsResponse]],
+ request: pubsub.ListTopicsRequest,
+ response: pubsub.ListTopicsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiates the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListTopicsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListTopicsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListTopicsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ async def pages(self) -> AsyncIterator[pubsub.ListTopicsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = await self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __aiter__(self) -> AsyncIterator[pubsub.Topic]:
+ async def async_generator():
+ async for page in self.pages:
+ for response in page.topics:
+ yield response
+
+ return async_generator()
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListTopicSubscriptionsPager:
+ """A pager for iterating through ``list_topic_subscriptions`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListTopicSubscriptionsResponse` object, and
+ provides an ``__iter__`` method to iterate through its
+ ``subscriptions`` field.
+
+ If there are more pages, the ``__iter__`` method will make additional
+ ``ListTopicSubscriptions`` requests and continue to iterate
+ through the ``subscriptions`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListTopicSubscriptionsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., pubsub.ListTopicSubscriptionsResponse],
+ request: pubsub.ListTopicSubscriptionsRequest,
+ response: pubsub.ListTopicSubscriptionsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiate the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListTopicSubscriptionsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListTopicSubscriptionsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListTopicSubscriptionsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ def pages(self) -> Iterator[pubsub.ListTopicSubscriptionsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __iter__(self) -> Iterator[str]:
+ for page in self.pages:
+ yield from page.subscriptions
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListTopicSubscriptionsAsyncPager:
+ """A pager for iterating through ``list_topic_subscriptions`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListTopicSubscriptionsResponse` object, and
+ provides an ``__aiter__`` method to iterate through its
+ ``subscriptions`` field.
+
+ If there are more pages, the ``__aiter__`` method will make additional
+ ``ListTopicSubscriptions`` requests and continue to iterate
+ through the ``subscriptions`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListTopicSubscriptionsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., Awaitable[pubsub.ListTopicSubscriptionsResponse]],
+ request: pubsub.ListTopicSubscriptionsRequest,
+ response: pubsub.ListTopicSubscriptionsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiates the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListTopicSubscriptionsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListTopicSubscriptionsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListTopicSubscriptionsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ async def pages(self) -> AsyncIterator[pubsub.ListTopicSubscriptionsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = await self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __aiter__(self) -> AsyncIterator[str]:
+ async def async_generator():
+ async for page in self.pages:
+ for response in page.subscriptions:
+ yield response
+
+ return async_generator()
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListTopicSnapshotsPager:
+ """A pager for iterating through ``list_topic_snapshots`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListTopicSnapshotsResponse` object, and
+ provides an ``__iter__`` method to iterate through its
+ ``snapshots`` field.
+
+ If there are more pages, the ``__iter__`` method will make additional
+ ``ListTopicSnapshots`` requests and continue to iterate
+ through the ``snapshots`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListTopicSnapshotsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., pubsub.ListTopicSnapshotsResponse],
+ request: pubsub.ListTopicSnapshotsRequest,
+ response: pubsub.ListTopicSnapshotsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiate the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListTopicSnapshotsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListTopicSnapshotsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListTopicSnapshotsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ def pages(self) -> Iterator[pubsub.ListTopicSnapshotsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __iter__(self) -> Iterator[str]:
+ for page in self.pages:
+ yield from page.snapshots
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListTopicSnapshotsAsyncPager:
+ """A pager for iterating through ``list_topic_snapshots`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListTopicSnapshotsResponse` object, and
+ provides an ``__aiter__`` method to iterate through its
+ ``snapshots`` field.
+
+ If there are more pages, the ``__aiter__`` method will make additional
+ ``ListTopicSnapshots`` requests and continue to iterate
+ through the ``snapshots`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListTopicSnapshotsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., Awaitable[pubsub.ListTopicSnapshotsResponse]],
+ request: pubsub.ListTopicSnapshotsRequest,
+ response: pubsub.ListTopicSnapshotsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiates the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListTopicSnapshotsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListTopicSnapshotsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListTopicSnapshotsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ async def pages(self) -> AsyncIterator[pubsub.ListTopicSnapshotsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = await self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __aiter__(self) -> AsyncIterator[str]:
+ async def async_generator():
+ async for page in self.pages:
+ for response in page.snapshots:
+ yield response
+
+ return async_generator()
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/__init__.py
new file mode 100644
index 000000000000..e73fe8901f80
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/__init__.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+from typing import Dict, Type
+
+from .base import PublisherTransport
+from .grpc import PublisherGrpcTransport
+from .grpc_asyncio import PublisherGrpcAsyncIOTransport
+
+
+# Compile a registry of transports.
+_transport_registry = OrderedDict() # type: Dict[str, Type[PublisherTransport]]
+_transport_registry["grpc"] = PublisherGrpcTransport
+_transport_registry["grpc_asyncio"] = PublisherGrpcAsyncIOTransport
+
+__all__ = (
+ "PublisherTransport",
+ "PublisherGrpcTransport",
+ "PublisherGrpcAsyncIOTransport",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/base.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/base.py
new file mode 100644
index 000000000000..11c085ffa7c0
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/base.py
@@ -0,0 +1,406 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import abc
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Union
+import pkg_resources
+
+import google.auth # type: ignore
+import google.api_core
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import pubsub
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+class PublisherTransport(abc.ABC):
+ """Abstract transport class for Publisher."""
+
+ AUTH_SCOPES = (
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/pubsub",
+ )
+
+ DEFAULT_HOST: str = "pubsub.googleapis.com"
+
+ def __init__(
+ self,
+ *,
+ host: str = DEFAULT_HOST,
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ **kwargs,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A list of scopes.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+ """
+
+ scopes_kwargs = {"scopes": scopes, "default_scopes": self.AUTH_SCOPES}
+
+ # Save the scopes.
+ self._scopes = scopes
+
+ # If no credentials are provided, then determine the appropriate
+ # defaults.
+ if credentials and credentials_file:
+ raise core_exceptions.DuplicateCredentialArgs(
+ "'credentials_file' and 'credentials' are mutually exclusive"
+ )
+
+ if credentials_file is not None:
+ credentials, _ = google.auth.load_credentials_from_file(
+ credentials_file, **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ elif credentials is None:
+ credentials, _ = google.auth.default(
+ **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ # Don't apply audience if the credentials file passed from user.
+ if hasattr(credentials, "with_gdch_audience"):
+ credentials = credentials.with_gdch_audience(
+ api_audience if api_audience else host
+ )
+
+ # If the credentials are service account credentials, then always try to use self signed JWT.
+ if (
+ always_use_jwt_access
+ and isinstance(credentials, service_account.Credentials)
+ and hasattr(service_account.Credentials, "with_always_use_jwt_access")
+ ):
+ credentials = credentials.with_always_use_jwt_access(True)
+
+ # Save the credentials.
+ self._credentials = credentials
+
+ # Save the hostname. Default to port 443 (HTTPS) if none is specified.
+ if ":" not in host:
+ host += ":443"
+ self._host = host
+
+ def _prep_wrapped_messages(self, client_info):
+ # Precompute the wrapped methods.
+ self._wrapped_methods = {
+ self.create_topic: gapic_v1.method.wrap_method(
+ self.create_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.update_topic: gapic_v1.method.wrap_method(
+ self.update_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.publish: gapic_v1.method.wrap_method(
+ self.publish,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.Cancelled,
+ core_exceptions.DeadlineExceeded,
+ core_exceptions.InternalServerError,
+ core_exceptions.ResourceExhausted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.get_topic: gapic_v1.method.wrap_method(
+ self.get_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.list_topics: gapic_v1.method.wrap_method(
+ self.list_topics,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.list_topic_subscriptions: gapic_v1.method.wrap_method(
+ self.list_topic_subscriptions,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.list_topic_snapshots: gapic_v1.method.wrap_method(
+ self.list_topic_snapshots,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.delete_topic: gapic_v1.method.wrap_method(
+ self.delete_topic,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.detach_subscription: gapic_v1.method.wrap_method(
+ self.detach_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=600.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ }
+
+ def close(self):
+ """Closes resources associated with the transport.
+
+ .. warning::
+ Only call this method if the transport is NOT shared
+ with other clients - this may cause errors in other clients!
+ """
+ raise NotImplementedError()
+
+ @property
+ def create_topic(
+ self,
+ ) -> Callable[[pubsub.Topic], Union[pubsub.Topic, Awaitable[pubsub.Topic]]]:
+ raise NotImplementedError()
+
+ @property
+ def update_topic(
+ self,
+ ) -> Callable[
+ [pubsub.UpdateTopicRequest], Union[pubsub.Topic, Awaitable[pubsub.Topic]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def publish(
+ self,
+ ) -> Callable[
+ [pubsub.PublishRequest],
+ Union[pubsub.PublishResponse, Awaitable[pubsub.PublishResponse]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def get_topic(
+ self,
+ ) -> Callable[
+ [pubsub.GetTopicRequest], Union[pubsub.Topic, Awaitable[pubsub.Topic]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def list_topics(
+ self,
+ ) -> Callable[
+ [pubsub.ListTopicsRequest],
+ Union[pubsub.ListTopicsResponse, Awaitable[pubsub.ListTopicsResponse]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def list_topic_subscriptions(
+ self,
+ ) -> Callable[
+ [pubsub.ListTopicSubscriptionsRequest],
+ Union[
+ pubsub.ListTopicSubscriptionsResponse,
+ Awaitable[pubsub.ListTopicSubscriptionsResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def list_topic_snapshots(
+ self,
+ ) -> Callable[
+ [pubsub.ListTopicSnapshotsRequest],
+ Union[
+ pubsub.ListTopicSnapshotsResponse,
+ Awaitable[pubsub.ListTopicSnapshotsResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def delete_topic(
+ self,
+ ) -> Callable[
+ [pubsub.DeleteTopicRequest], Union[empty_pb2.Empty, Awaitable[empty_pb2.Empty]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def detach_subscription(
+ self,
+ ) -> Callable[
+ [pubsub.DetachSubscriptionRequest],
+ Union[
+ pubsub.DetachSubscriptionResponse,
+ Awaitable[pubsub.DetachSubscriptionResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.SetIamPolicyRequest],
+ Union[policy_pb2.Policy, Awaitable[policy_pb2.Policy]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.GetIamPolicyRequest],
+ Union[policy_pb2.Policy, Awaitable[policy_pb2.Policy]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ Union[
+ iam_policy_pb2.TestIamPermissionsResponse,
+ Awaitable[iam_policy_pb2.TestIamPermissionsResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def kind(self) -> str:
+ raise NotImplementedError()
+
+
+__all__ = ("PublisherTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/grpc.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/grpc.py
new file mode 100644
index 000000000000..0d41c36f2a13
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/grpc.py
@@ -0,0 +1,575 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import warnings
+from typing import Callable, Dict, Optional, Sequence, Tuple, Union
+
+from google.api_core import grpc_helpers
+from google.api_core import gapic_v1
+import google.auth # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+
+import grpc # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import pubsub
+from .base import PublisherTransport, DEFAULT_CLIENT_INFO
+
+
+class PublisherGrpcTransport(PublisherTransport):
+ """gRPC backend transport for Publisher.
+
+ The service that an application uses to manipulate topics,
+ and to send messages to a topic.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _stubs: Dict[str, Callable]
+
+ def __init__(
+ self,
+ *,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Sequence[str] = None,
+ channel: grpc.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional(Sequence[str])): A list of scopes. This argument is
+ ignored if ``channel`` is provided.
+ channel (Optional[grpc.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ("grpc.max_metadata_size", 4 * 1024 * 1024),
+ ("grpc.keepalive_time_ms", 30000),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> grpc.Channel:
+ """Create and return a gRPC channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ grpc.Channel: A gRPC channel object.
+
+ Raises:
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+
+ return grpc_helpers.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ @property
+ def grpc_channel(self) -> grpc.Channel:
+ """Return the channel designed to connect to this service."""
+ return self._grpc_channel
+
+ @property
+ def create_topic(self) -> Callable[[pubsub.Topic], pubsub.Topic]:
+ r"""Return a callable for the create topic method over gRPC.
+
+ Creates the given topic with the given name. See the [resource
+ name rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names).
+
+ Returns:
+ Callable[[~.Topic],
+ ~.Topic]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_topic" not in self._stubs:
+ self._stubs["create_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/CreateTopic",
+ request_serializer=pubsub.Topic.serialize,
+ response_deserializer=pubsub.Topic.deserialize,
+ )
+ return self._stubs["create_topic"]
+
+ @property
+ def update_topic(self) -> Callable[[pubsub.UpdateTopicRequest], pubsub.Topic]:
+ r"""Return a callable for the update topic method over gRPC.
+
+ Updates an existing topic. Note that certain
+ properties of a topic are not modifiable.
+
+ Returns:
+ Callable[[~.UpdateTopicRequest],
+ ~.Topic]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "update_topic" not in self._stubs:
+ self._stubs["update_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/UpdateTopic",
+ request_serializer=pubsub.UpdateTopicRequest.serialize,
+ response_deserializer=pubsub.Topic.deserialize,
+ )
+ return self._stubs["update_topic"]
+
+ @property
+ def publish(self) -> Callable[[pubsub.PublishRequest], pubsub.PublishResponse]:
+ r"""Return a callable for the publish method over gRPC.
+
+ Adds one or more messages to the topic. Returns ``NOT_FOUND`` if
+ the topic does not exist.
+
+ Returns:
+ Callable[[~.PublishRequest],
+ ~.PublishResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "publish" not in self._stubs:
+ self._stubs["publish"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/Publish",
+ request_serializer=pubsub.PublishRequest.serialize,
+ response_deserializer=pubsub.PublishResponse.deserialize,
+ )
+ return self._stubs["publish"]
+
+ @property
+ def get_topic(self) -> Callable[[pubsub.GetTopicRequest], pubsub.Topic]:
+ r"""Return a callable for the get topic method over gRPC.
+
+ Gets the configuration of a topic.
+
+ Returns:
+ Callable[[~.GetTopicRequest],
+ ~.Topic]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_topic" not in self._stubs:
+ self._stubs["get_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/GetTopic",
+ request_serializer=pubsub.GetTopicRequest.serialize,
+ response_deserializer=pubsub.Topic.deserialize,
+ )
+ return self._stubs["get_topic"]
+
+ @property
+ def list_topics(
+ self,
+ ) -> Callable[[pubsub.ListTopicsRequest], pubsub.ListTopicsResponse]:
+ r"""Return a callable for the list topics method over gRPC.
+
+ Lists matching topics.
+
+ Returns:
+ Callable[[~.ListTopicsRequest],
+ ~.ListTopicsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_topics" not in self._stubs:
+ self._stubs["list_topics"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/ListTopics",
+ request_serializer=pubsub.ListTopicsRequest.serialize,
+ response_deserializer=pubsub.ListTopicsResponse.deserialize,
+ )
+ return self._stubs["list_topics"]
+
+ @property
+ def list_topic_subscriptions(
+ self,
+ ) -> Callable[
+ [pubsub.ListTopicSubscriptionsRequest], pubsub.ListTopicSubscriptionsResponse
+ ]:
+ r"""Return a callable for the list topic subscriptions method over gRPC.
+
+ Lists the names of the attached subscriptions on this
+ topic.
+
+ Returns:
+ Callable[[~.ListTopicSubscriptionsRequest],
+ ~.ListTopicSubscriptionsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_topic_subscriptions" not in self._stubs:
+ self._stubs["list_topic_subscriptions"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/ListTopicSubscriptions",
+ request_serializer=pubsub.ListTopicSubscriptionsRequest.serialize,
+ response_deserializer=pubsub.ListTopicSubscriptionsResponse.deserialize,
+ )
+ return self._stubs["list_topic_subscriptions"]
+
+ @property
+ def list_topic_snapshots(
+ self,
+ ) -> Callable[
+ [pubsub.ListTopicSnapshotsRequest], pubsub.ListTopicSnapshotsResponse
+ ]:
+ r"""Return a callable for the list topic snapshots method over gRPC.
+
+ Lists the names of the snapshots on this topic. Snapshots are
+ used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ Returns:
+ Callable[[~.ListTopicSnapshotsRequest],
+ ~.ListTopicSnapshotsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_topic_snapshots" not in self._stubs:
+ self._stubs["list_topic_snapshots"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/ListTopicSnapshots",
+ request_serializer=pubsub.ListTopicSnapshotsRequest.serialize,
+ response_deserializer=pubsub.ListTopicSnapshotsResponse.deserialize,
+ )
+ return self._stubs["list_topic_snapshots"]
+
+ @property
+ def delete_topic(self) -> Callable[[pubsub.DeleteTopicRequest], empty_pb2.Empty]:
+ r"""Return a callable for the delete topic method over gRPC.
+
+ Deletes the topic with the given name. Returns ``NOT_FOUND`` if
+ the topic does not exist. After a topic is deleted, a new topic
+ may be created with the same name; this is an entirely new topic
+ with none of the old configuration or subscriptions. Existing
+ subscriptions to this topic are not deleted, but their ``topic``
+ field is set to ``_deleted-topic_``.
+
+ Returns:
+ Callable[[~.DeleteTopicRequest],
+ ~.Empty]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_topic" not in self._stubs:
+ self._stubs["delete_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/DeleteTopic",
+ request_serializer=pubsub.DeleteTopicRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_topic"]
+
+ @property
+ def detach_subscription(
+ self,
+ ) -> Callable[
+ [pubsub.DetachSubscriptionRequest], pubsub.DetachSubscriptionResponse
+ ]:
+ r"""Return a callable for the detach subscription method over gRPC.
+
+ Detaches a subscription from this topic. All messages retained
+ in the subscription are dropped. Subsequent ``Pull`` and
+ ``StreamingPull`` requests will return FAILED_PRECONDITION. If
+ the subscription is a push subscription, pushes to the endpoint
+ will stop.
+
+ Returns:
+ Callable[[~.DetachSubscriptionRequest],
+ ~.DetachSubscriptionResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "detach_subscription" not in self._stubs:
+ self._stubs["detach_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/DetachSubscription",
+ request_serializer=pubsub.DetachSubscriptionRequest.serialize,
+ response_deserializer=pubsub.DetachSubscriptionResponse.deserialize,
+ )
+ return self._stubs["detach_subscription"]
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], policy_pb2.Policy]:
+ r"""Return a callable for the set iam policy method over gRPC.
+ Sets the IAM access control policy on the specified
+ function. Replaces any existing policy.
+ Returns:
+ Callable[[~.SetIamPolicyRequest],
+ ~.Policy]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "set_iam_policy" not in self._stubs:
+ self._stubs["set_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/SetIamPolicy",
+ request_serializer=iam_policy_pb2.SetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["set_iam_policy"]
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], policy_pb2.Policy]:
+ r"""Return a callable for the get iam policy method over gRPC.
+ Gets the IAM access control policy for a function.
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+ Returns:
+ Callable[[~.GetIamPolicyRequest],
+ ~.Policy]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_iam_policy" not in self._stubs:
+ self._stubs["get_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/GetIamPolicy",
+ request_serializer=iam_policy_pb2.GetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["get_iam_policy"]
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ iam_policy_pb2.TestIamPermissionsResponse,
+ ]:
+ r"""Return a callable for the test iam permissions method over gRPC.
+ Tests the specified permissions against the IAM access control
+ policy for a function. If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+ Returns:
+ Callable[[~.TestIamPermissionsRequest],
+ ~.TestIamPermissionsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "test_iam_permissions" not in self._stubs:
+ self._stubs["test_iam_permissions"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/TestIamPermissions",
+ request_serializer=iam_policy_pb2.TestIamPermissionsRequest.SerializeToString,
+ response_deserializer=iam_policy_pb2.TestIamPermissionsResponse.FromString,
+ )
+ return self._stubs["test_iam_permissions"]
+
+ def close(self):
+ self.grpc_channel.close()
+
+ @property
+ def kind(self) -> str:
+ return "grpc"
+
+
+__all__ = ("PublisherGrpcTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/grpc_asyncio.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/grpc_asyncio.py
new file mode 100644
index 000000000000..e236c165cae7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/transports/grpc_asyncio.py
@@ -0,0 +1,581 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import warnings
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Tuple, Union
+
+from google.api_core import gapic_v1
+from google.api_core import grpc_helpers_async
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+
+import grpc # type: ignore
+from grpc.experimental import aio # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import pubsub
+from .base import PublisherTransport, DEFAULT_CLIENT_INFO
+from .grpc import PublisherGrpcTransport
+
+
+class PublisherGrpcAsyncIOTransport(PublisherTransport):
+ """gRPC AsyncIO backend transport for Publisher.
+
+ The service that an application uses to manipulate topics,
+ and to send messages to a topic.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _grpc_channel: aio.Channel
+ _stubs: Dict[str, Callable] = {}
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> aio.Channel:
+ """Create and return a gRPC AsyncIO channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ aio.Channel: A gRPC AsyncIO channel object.
+ """
+
+ return grpc_helpers_async.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ def __init__(
+ self,
+ *,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ channel: aio.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id=None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ channel (Optional[aio.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ("grpc.max_metadata_size", 4 * 1024 * 1024),
+ ("grpc.keepalive_time_ms", 30000),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @property
+ def grpc_channel(self) -> aio.Channel:
+ """Create the channel designed to connect to this service.
+
+ This property caches on the instance; repeated calls return
+ the same channel.
+ """
+ # Return the channel from cache.
+ return self._grpc_channel
+
+ @property
+ def create_topic(self) -> Callable[[pubsub.Topic], Awaitable[pubsub.Topic]]:
+ r"""Return a callable for the create topic method over gRPC.
+
+ Creates the given topic with the given name. See the [resource
+ name rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names).
+
+ Returns:
+ Callable[[~.Topic],
+ Awaitable[~.Topic]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_topic" not in self._stubs:
+ self._stubs["create_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/CreateTopic",
+ request_serializer=pubsub.Topic.serialize,
+ response_deserializer=pubsub.Topic.deserialize,
+ )
+ return self._stubs["create_topic"]
+
+ @property
+ def update_topic(
+ self,
+ ) -> Callable[[pubsub.UpdateTopicRequest], Awaitable[pubsub.Topic]]:
+ r"""Return a callable for the update topic method over gRPC.
+
+ Updates an existing topic. Note that certain
+ properties of a topic are not modifiable.
+
+ Returns:
+ Callable[[~.UpdateTopicRequest],
+ Awaitable[~.Topic]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "update_topic" not in self._stubs:
+ self._stubs["update_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/UpdateTopic",
+ request_serializer=pubsub.UpdateTopicRequest.serialize,
+ response_deserializer=pubsub.Topic.deserialize,
+ )
+ return self._stubs["update_topic"]
+
+ @property
+ def publish(
+ self,
+ ) -> Callable[[pubsub.PublishRequest], Awaitable[pubsub.PublishResponse]]:
+ r"""Return a callable for the publish method over gRPC.
+
+ Adds one or more messages to the topic. Returns ``NOT_FOUND`` if
+ the topic does not exist.
+
+ Returns:
+ Callable[[~.PublishRequest],
+ Awaitable[~.PublishResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "publish" not in self._stubs:
+ self._stubs["publish"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/Publish",
+ request_serializer=pubsub.PublishRequest.serialize,
+ response_deserializer=pubsub.PublishResponse.deserialize,
+ )
+ return self._stubs["publish"]
+
+ @property
+ def get_topic(self) -> Callable[[pubsub.GetTopicRequest], Awaitable[pubsub.Topic]]:
+ r"""Return a callable for the get topic method over gRPC.
+
+ Gets the configuration of a topic.
+
+ Returns:
+ Callable[[~.GetTopicRequest],
+ Awaitable[~.Topic]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_topic" not in self._stubs:
+ self._stubs["get_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/GetTopic",
+ request_serializer=pubsub.GetTopicRequest.serialize,
+ response_deserializer=pubsub.Topic.deserialize,
+ )
+ return self._stubs["get_topic"]
+
+ @property
+ def list_topics(
+ self,
+ ) -> Callable[[pubsub.ListTopicsRequest], Awaitable[pubsub.ListTopicsResponse]]:
+ r"""Return a callable for the list topics method over gRPC.
+
+ Lists matching topics.
+
+ Returns:
+ Callable[[~.ListTopicsRequest],
+ Awaitable[~.ListTopicsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_topics" not in self._stubs:
+ self._stubs["list_topics"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/ListTopics",
+ request_serializer=pubsub.ListTopicsRequest.serialize,
+ response_deserializer=pubsub.ListTopicsResponse.deserialize,
+ )
+ return self._stubs["list_topics"]
+
+ @property
+ def list_topic_subscriptions(
+ self,
+ ) -> Callable[
+ [pubsub.ListTopicSubscriptionsRequest],
+ Awaitable[pubsub.ListTopicSubscriptionsResponse],
+ ]:
+ r"""Return a callable for the list topic subscriptions method over gRPC.
+
+ Lists the names of the attached subscriptions on this
+ topic.
+
+ Returns:
+ Callable[[~.ListTopicSubscriptionsRequest],
+ Awaitable[~.ListTopicSubscriptionsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_topic_subscriptions" not in self._stubs:
+ self._stubs["list_topic_subscriptions"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/ListTopicSubscriptions",
+ request_serializer=pubsub.ListTopicSubscriptionsRequest.serialize,
+ response_deserializer=pubsub.ListTopicSubscriptionsResponse.deserialize,
+ )
+ return self._stubs["list_topic_subscriptions"]
+
+ @property
+ def list_topic_snapshots(
+ self,
+ ) -> Callable[
+ [pubsub.ListTopicSnapshotsRequest], Awaitable[pubsub.ListTopicSnapshotsResponse]
+ ]:
+ r"""Return a callable for the list topic snapshots method over gRPC.
+
+ Lists the names of the snapshots on this topic. Snapshots are
+ used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ Returns:
+ Callable[[~.ListTopicSnapshotsRequest],
+ Awaitable[~.ListTopicSnapshotsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_topic_snapshots" not in self._stubs:
+ self._stubs["list_topic_snapshots"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/ListTopicSnapshots",
+ request_serializer=pubsub.ListTopicSnapshotsRequest.serialize,
+ response_deserializer=pubsub.ListTopicSnapshotsResponse.deserialize,
+ )
+ return self._stubs["list_topic_snapshots"]
+
+ @property
+ def delete_topic(
+ self,
+ ) -> Callable[[pubsub.DeleteTopicRequest], Awaitable[empty_pb2.Empty]]:
+ r"""Return a callable for the delete topic method over gRPC.
+
+ Deletes the topic with the given name. Returns ``NOT_FOUND`` if
+ the topic does not exist. After a topic is deleted, a new topic
+ may be created with the same name; this is an entirely new topic
+ with none of the old configuration or subscriptions. Existing
+ subscriptions to this topic are not deleted, but their ``topic``
+ field is set to ``_deleted-topic_``.
+
+ Returns:
+ Callable[[~.DeleteTopicRequest],
+ Awaitable[~.Empty]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_topic" not in self._stubs:
+ self._stubs["delete_topic"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/DeleteTopic",
+ request_serializer=pubsub.DeleteTopicRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_topic"]
+
+ @property
+ def detach_subscription(
+ self,
+ ) -> Callable[
+ [pubsub.DetachSubscriptionRequest], Awaitable[pubsub.DetachSubscriptionResponse]
+ ]:
+ r"""Return a callable for the detach subscription method over gRPC.
+
+ Detaches a subscription from this topic. All messages retained
+ in the subscription are dropped. Subsequent ``Pull`` and
+ ``StreamingPull`` requests will return FAILED_PRECONDITION. If
+ the subscription is a push subscription, pushes to the endpoint
+ will stop.
+
+ Returns:
+ Callable[[~.DetachSubscriptionRequest],
+ Awaitable[~.DetachSubscriptionResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "detach_subscription" not in self._stubs:
+ self._stubs["detach_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Publisher/DetachSubscription",
+ request_serializer=pubsub.DetachSubscriptionRequest.serialize,
+ response_deserializer=pubsub.DetachSubscriptionResponse.deserialize,
+ )
+ return self._stubs["detach_subscription"]
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], Awaitable[policy_pb2.Policy]]:
+ r"""Return a callable for the set iam policy method over gRPC.
+ Sets the IAM access control policy on the specified
+ function. Replaces any existing policy.
+ Returns:
+ Callable[[~.SetIamPolicyRequest],
+ Awaitable[~.Policy]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "set_iam_policy" not in self._stubs:
+ self._stubs["set_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/SetIamPolicy",
+ request_serializer=iam_policy_pb2.SetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["set_iam_policy"]
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], Awaitable[policy_pb2.Policy]]:
+ r"""Return a callable for the get iam policy method over gRPC.
+ Gets the IAM access control policy for a function.
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+ Returns:
+ Callable[[~.GetIamPolicyRequest],
+ Awaitable[~.Policy]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_iam_policy" not in self._stubs:
+ self._stubs["get_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/GetIamPolicy",
+ request_serializer=iam_policy_pb2.GetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["get_iam_policy"]
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ Awaitable[iam_policy_pb2.TestIamPermissionsResponse],
+ ]:
+ r"""Return a callable for the test iam permissions method over gRPC.
+ Tests the specified permissions against the IAM access control
+ policy for a function. If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+ Returns:
+ Callable[[~.TestIamPermissionsRequest],
+ Awaitable[~.TestIamPermissionsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "test_iam_permissions" not in self._stubs:
+ self._stubs["test_iam_permissions"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/TestIamPermissions",
+ request_serializer=iam_policy_pb2.TestIamPermissionsRequest.SerializeToString,
+ response_deserializer=iam_policy_pb2.TestIamPermissionsResponse.FromString,
+ )
+ return self._stubs["test_iam_permissions"]
+
+ def close(self):
+ return self.grpc_channel.close()
+
+
+__all__ = ("PublisherGrpcAsyncIOTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/__init__.py
new file mode 100644
index 000000000000..2609e9ecd722
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from .client import SchemaServiceClient
+from .async_client import SchemaServiceAsyncClient
+
+__all__ = (
+ "SchemaServiceClient",
+ "SchemaServiceAsyncClient",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/async_client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/async_client.py
new file mode 100644
index 000000000000..f0f158b6fac4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/async_client.py
@@ -0,0 +1,1154 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import functools
+import re
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
+import pkg_resources
+
+from google.api_core.client_options import ClientOptions
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.pubsub_v1.services.schema_service import pagers
+from google.pubsub_v1.types import schema
+from google.pubsub_v1.types import schema as gp_schema
+from .transports.base import SchemaServiceTransport, DEFAULT_CLIENT_INFO
+from .transports.grpc_asyncio import SchemaServiceGrpcAsyncIOTransport
+from .client import SchemaServiceClient
+
+
+class SchemaServiceAsyncClient:
+ """Service for doing schema-related operations."""
+
+ _client: SchemaServiceClient
+
+ DEFAULT_ENDPOINT = SchemaServiceClient.DEFAULT_ENDPOINT
+ DEFAULT_MTLS_ENDPOINT = SchemaServiceClient.DEFAULT_MTLS_ENDPOINT
+
+ schema_path = staticmethod(SchemaServiceClient.schema_path)
+ parse_schema_path = staticmethod(SchemaServiceClient.parse_schema_path)
+ common_billing_account_path = staticmethod(
+ SchemaServiceClient.common_billing_account_path
+ )
+ parse_common_billing_account_path = staticmethod(
+ SchemaServiceClient.parse_common_billing_account_path
+ )
+ common_folder_path = staticmethod(SchemaServiceClient.common_folder_path)
+ parse_common_folder_path = staticmethod(
+ SchemaServiceClient.parse_common_folder_path
+ )
+ common_organization_path = staticmethod(
+ SchemaServiceClient.common_organization_path
+ )
+ parse_common_organization_path = staticmethod(
+ SchemaServiceClient.parse_common_organization_path
+ )
+ common_project_path = staticmethod(SchemaServiceClient.common_project_path)
+ parse_common_project_path = staticmethod(
+ SchemaServiceClient.parse_common_project_path
+ )
+ common_location_path = staticmethod(SchemaServiceClient.common_location_path)
+ parse_common_location_path = staticmethod(
+ SchemaServiceClient.parse_common_location_path
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SchemaServiceAsyncClient: The constructed client.
+ """
+ return SchemaServiceClient.from_service_account_info.__func__(SchemaServiceAsyncClient, info, *args, **kwargs) # type: ignore
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SchemaServiceAsyncClient: The constructed client.
+ """
+ return SchemaServiceClient.from_service_account_file.__func__(SchemaServiceAsyncClient, filename, *args, **kwargs) # type: ignore
+
+ from_service_account_json = from_service_account_file
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ return SchemaServiceClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore
+
+ @property
+ def transport(self) -> SchemaServiceTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ SchemaServiceTransport: The transport used by the client instance.
+ """
+ return self._client.transport
+
+ get_transport_class = functools.partial(
+ type(SchemaServiceClient).get_transport_class, type(SchemaServiceClient)
+ )
+
+ def __init__(
+ self,
+ *,
+ credentials: ga_credentials.Credentials = None,
+ transport: Union[str, SchemaServiceTransport] = "grpc_asyncio",
+ client_options: ClientOptions = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the schema service client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, ~.SchemaServiceTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (ClientOptions): Custom options for the client. It
+ won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ self._client = SchemaServiceClient(
+ credentials=credentials,
+ transport=transport,
+ client_options=client_options,
+ client_info=client_info,
+ )
+
+ async def create_schema(
+ self,
+ request: Union[gp_schema.CreateSchemaRequest, dict] = None,
+ *,
+ parent: str = None,
+ schema: gp_schema.Schema = None,
+ schema_id: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> gp_schema.Schema:
+ r"""Creates a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_create_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceAsyncClient()
+
+ # Initialize request argument(s)
+ schema = pubsub_v1.Schema()
+ schema.name = "name_value"
+
+ request = pubsub_v1.CreateSchemaRequest(
+ parent="parent_value",
+ schema=schema,
+ )
+
+ # Make the request
+ response = await client.create_schema(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.CreateSchemaRequest, dict]):
+ The request object. Request for the CreateSchema method.
+ parent (:class:`str`):
+ Required. The name of the project in which to create the
+ schema. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``parent`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ schema (:class:`google.pubsub_v1.types.Schema`):
+ Required. The schema object to create.
+
+ This schema's ``name`` parameter is ignored. The schema
+ object returned by CreateSchema will have a ``name``
+ made using the given ``parent`` and ``schema_id``.
+
+ This corresponds to the ``schema`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ schema_id (:class:`str`):
+ The ID to use for the schema, which will become the
+ final component of the schema's resource name.
+
+ See
+ https://cloud.google.com/pubsub/docs/admin#resource_names
+ for resource name constraints.
+
+ This corresponds to the ``schema_id`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Schema:
+ A schema resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([parent, schema, schema_id])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = gp_schema.CreateSchemaRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if parent is not None:
+ request.parent = parent
+ if schema is not None:
+ request.schema = schema
+ if schema_id is not None:
+ request.schema_id = schema_id
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.create_schema,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def get_schema(
+ self,
+ request: Union[schema.GetSchemaRequest, dict] = None,
+ *,
+ name: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> schema.Schema:
+ r"""Gets a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_get_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetSchemaRequest(
+ name="name_value",
+ )
+
+ # Make the request
+ response = await client.get_schema(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetSchemaRequest, dict]):
+ The request object. Request for the GetSchema method.
+ name (:class:`str`):
+ Required. The name of the schema to get. Format is
+ ``projects/{project}/schemas/{schema}``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Schema:
+ A schema resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = schema.GetSchemaRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.get_schema,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def list_schemas(
+ self,
+ request: Union[schema.ListSchemasRequest, dict] = None,
+ *,
+ parent: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListSchemasAsyncPager:
+ r"""Lists schemas in a project.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_list_schemas():
+ # Create a client
+ client = pubsub_v1.SchemaServiceAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListSchemasRequest(
+ parent="parent_value",
+ )
+
+ # Make the request
+ page_result = client.list_schemas(request=request)
+
+ # Handle the response
+ async for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListSchemasRequest, dict]):
+ The request object. Request for the `ListSchemas`
+ method.
+ parent (:class:`str`):
+ Required. The name of the project in which to list
+ schemas. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``parent`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.schema_service.pagers.ListSchemasAsyncPager:
+ Response for the ListSchemas method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([parent])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = schema.ListSchemasRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if parent is not None:
+ request.parent = parent
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_schemas,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__aiter__` convenience method.
+ response = pagers.ListSchemasAsyncPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def delete_schema(
+ self,
+ request: Union[schema.DeleteSchemaRequest, dict] = None,
+ *,
+ name: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Deletes a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_delete_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteSchemaRequest(
+ name="name_value",
+ )
+
+ # Make the request
+ await client.delete_schema(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteSchemaRequest, dict]):
+ The request object. Request for the `DeleteSchema`
+ method.
+ name (:class:`str`):
+ Required. Name of the schema to delete. Format is
+ ``projects/{project}/schemas/{schema}``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = schema.DeleteSchemaRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.delete_schema,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ async def validate_schema(
+ self,
+ request: Union[gp_schema.ValidateSchemaRequest, dict] = None,
+ *,
+ parent: str = None,
+ schema: gp_schema.Schema = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> gp_schema.ValidateSchemaResponse:
+ r"""Validates a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_validate_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceAsyncClient()
+
+ # Initialize request argument(s)
+ schema = pubsub_v1.Schema()
+ schema.name = "name_value"
+
+ request = pubsub_v1.ValidateSchemaRequest(
+ parent="parent_value",
+ schema=schema,
+ )
+
+ # Make the request
+ response = await client.validate_schema(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ValidateSchemaRequest, dict]):
+ The request object. Request for the `ValidateSchema`
+ method.
+ parent (:class:`str`):
+ Required. The name of the project in which to validate
+ schemas. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``parent`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ schema (:class:`google.pubsub_v1.types.Schema`):
+ Required. The schema object to
+ validate.
+
+ This corresponds to the ``schema`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.ValidateSchemaResponse:
+ Response for the ValidateSchema method.
+ Empty for now.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([parent, schema])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = gp_schema.ValidateSchemaRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if parent is not None:
+ request.parent = parent
+ if schema is not None:
+ request.schema = schema
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.validate_schema,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def validate_message(
+ self,
+ request: Union[schema.ValidateMessageRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> schema.ValidateMessageResponse:
+ r"""Validates a message against a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_validate_message():
+ # Create a client
+ client = pubsub_v1.SchemaServiceAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ValidateMessageRequest(
+ name="name_value",
+ parent="parent_value",
+ )
+
+ # Make the request
+ response = await client.validate_message(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ValidateMessageRequest, dict]):
+ The request object. Request for the `ValidateMessage`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.ValidateMessageResponse:
+ Response for the ValidateMessage method.
+ Empty for now.
+
+ """
+ # Create or coerce a protobuf request object.
+ request = schema.ValidateMessageRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.validate_message,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def set_iam_policy(
+ self,
+ request: iam_policy_pb2.SetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Sets the IAM access control policy on the specified function.
+
+ Replaces any existing policy.
+
+ Args:
+ request (:class:`~.policy_pb2.SetIamPolicyRequest`):
+ The request object. Request message for `SetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.SetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.set_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def get_iam_policy(
+ self,
+ request: iam_policy_pb2.GetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Gets the IAM access control policy for a function.
+
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.GetIamPolicyRequest`):
+ The request object. Request message for `GetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.GetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.get_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def test_iam_permissions(
+ self,
+ request: iam_policy_pb2.TestIamPermissionsRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> iam_policy_pb2.TestIamPermissionsResponse:
+ r"""Tests the specified permissions against the IAM access control
+ policy for a function.
+
+ If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.TestIamPermissionsRequest`):
+ The request object. Request message for
+ `TestIamPermissions` method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~iam_policy_pb2.PolicyTestIamPermissionsResponse:
+ Response message for ``TestIamPermissions`` method.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.TestIamPermissionsRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.test_iam_permissions,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb):
+ await self.transport.close()
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("SchemaServiceAsyncClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/client.py
new file mode 100644
index 000000000000..9ecff30f4991
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/client.py
@@ -0,0 +1,1393 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import functools
+import os
+import re
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Type, Union
+import pkg_resources
+
+from google.api_core import client_options as client_options_lib
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport import mtls # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+from google.auth.exceptions import MutualTLSChannelError # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.pubsub_v1.services.schema_service import pagers
+from google.pubsub_v1.types import schema
+from google.pubsub_v1.types import schema as gp_schema
+
+import grpc
+from .transports.base import SchemaServiceTransport, DEFAULT_CLIENT_INFO
+from .transports.grpc import SchemaServiceGrpcTransport
+from .transports.grpc_asyncio import SchemaServiceGrpcAsyncIOTransport
+
+
+class SchemaServiceClientMeta(type):
+ """Metaclass for the SchemaService client.
+
+ This provides class-level methods for building and retrieving
+ support objects (e.g. transport) without polluting the client instance
+ objects.
+ """
+
+ _transport_registry = OrderedDict() # type: Dict[str, Type[SchemaServiceTransport]]
+ _transport_registry["grpc"] = SchemaServiceGrpcTransport
+ _transport_registry["grpc_asyncio"] = SchemaServiceGrpcAsyncIOTransport
+
+ def get_transport_class(
+ cls,
+ label: str = None,
+ ) -> Type[SchemaServiceTransport]:
+ """Returns an appropriate transport class.
+
+ Args:
+ label: The name of the desired transport. If none is
+ provided, then the first transport in the registry is used.
+
+ Returns:
+ The transport class to use.
+ """
+ # If a specific transport is requested, return that one.
+ if label:
+ return cls._transport_registry[label]
+
+ # No transport is requested; return the default (that is, the first one
+ # in the dictionary).
+ return next(iter(cls._transport_registry.values()))
+
+
+class SchemaServiceClient(metaclass=SchemaServiceClientMeta):
+ """Service for doing schema-related operations."""
+
+ @staticmethod
+ def _get_default_mtls_endpoint(api_endpoint):
+ """Converts api endpoint to mTLS endpoint.
+
+ Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
+ "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
+ Args:
+ api_endpoint (Optional[str]): the api endpoint to convert.
+ Returns:
+ str: converted mTLS api endpoint.
+ """
+ if not api_endpoint:
+ return api_endpoint
+
+ mtls_endpoint_re = re.compile(
+ r"(?P[^.]+)(?P\.mtls)?(?P\.sandbox)?(?P\.googleapis\.com)?"
+ )
+
+ m = mtls_endpoint_re.match(api_endpoint)
+ name, mtls, sandbox, googledomain = m.groups()
+ if mtls or not googledomain:
+ return api_endpoint
+
+ if sandbox:
+ return api_endpoint.replace(
+ "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
+ )
+
+ return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
+
+ DEFAULT_ENDPOINT = "pubsub.googleapis.com"
+ DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore
+ DEFAULT_ENDPOINT
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SchemaServiceClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_info(info)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SchemaServiceClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_file(filename)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ from_service_account_json = from_service_account_file
+
+ @property
+ def transport(self) -> SchemaServiceTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ SchemaServiceTransport: The transport used by the client
+ instance.
+ """
+ return self._transport
+
+ @staticmethod
+ def schema_path(
+ project: str,
+ schema: str,
+ ) -> str:
+ """Returns a fully-qualified schema string."""
+ return "projects/{project}/schemas/{schema}".format(
+ project=project,
+ schema=schema,
+ )
+
+ @staticmethod
+ def parse_schema_path(path: str) -> Dict[str, str]:
+ """Parses a schema path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/schemas/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_billing_account_path(
+ billing_account: str,
+ ) -> str:
+ """Returns a fully-qualified billing_account string."""
+ return "billingAccounts/{billing_account}".format(
+ billing_account=billing_account,
+ )
+
+ @staticmethod
+ def parse_common_billing_account_path(path: str) -> Dict[str, str]:
+ """Parse a billing_account path into its component segments."""
+ m = re.match(r"^billingAccounts/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_folder_path(
+ folder: str,
+ ) -> str:
+ """Returns a fully-qualified folder string."""
+ return "folders/{folder}".format(
+ folder=folder,
+ )
+
+ @staticmethod
+ def parse_common_folder_path(path: str) -> Dict[str, str]:
+ """Parse a folder path into its component segments."""
+ m = re.match(r"^folders/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_organization_path(
+ organization: str,
+ ) -> str:
+ """Returns a fully-qualified organization string."""
+ return "organizations/{organization}".format(
+ organization=organization,
+ )
+
+ @staticmethod
+ def parse_common_organization_path(path: str) -> Dict[str, str]:
+ """Parse a organization path into its component segments."""
+ m = re.match(r"^organizations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_project_path(
+ project: str,
+ ) -> str:
+ """Returns a fully-qualified project string."""
+ return "projects/{project}".format(
+ project=project,
+ )
+
+ @staticmethod
+ def parse_common_project_path(path: str) -> Dict[str, str]:
+ """Parse a project path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_location_path(
+ project: str,
+ location: str,
+ ) -> str:
+ """Returns a fully-qualified location string."""
+ return "projects/{project}/locations/{location}".format(
+ project=project,
+ location=location,
+ )
+
+ @staticmethod
+ def parse_common_location_path(path: str) -> Dict[str, str]:
+ """Parse a location path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/locations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[client_options_lib.ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+ use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
+ use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
+ if use_client_cert not in ("true", "false"):
+ raise ValueError(
+ "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"
+ )
+ if use_mtls_endpoint not in ("auto", "never", "always"):
+ raise MutualTLSChannelError(
+ "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"
+ )
+
+ # Figure out the client cert source to use.
+ client_cert_source = None
+ if use_client_cert == "true":
+ if client_options.client_cert_source:
+ client_cert_source = client_options.client_cert_source
+ elif mtls.has_default_client_cert_source():
+ client_cert_source = mtls.default_client_cert_source()
+
+ # Figure out which api endpoint to use.
+ if client_options.api_endpoint is not None:
+ api_endpoint = client_options.api_endpoint
+ elif use_mtls_endpoint == "always" or (
+ use_mtls_endpoint == "auto" and client_cert_source
+ ):
+ api_endpoint = cls.DEFAULT_MTLS_ENDPOINT
+ else:
+ api_endpoint = cls.DEFAULT_ENDPOINT
+
+ return api_endpoint, client_cert_source
+
+ def __init__(
+ self,
+ *,
+ credentials: Optional[ga_credentials.Credentials] = None,
+ transport: Union[str, SchemaServiceTransport, None] = None,
+ client_options: Optional[client_options_lib.ClientOptions] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the schema service client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, SchemaServiceTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. It won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ if isinstance(client_options, dict):
+ client_options = client_options_lib.from_dict(client_options)
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+
+ api_endpoint, client_cert_source_func = self.get_mtls_endpoint_and_cert_source(
+ client_options
+ )
+
+ api_key_value = getattr(client_options, "api_key", None)
+ if api_key_value and credentials:
+ raise ValueError(
+ "client_options.api_key and credentials are mutually exclusive"
+ )
+
+ # Save or instantiate the transport.
+ # Ordinarily, we provide the transport, but allowing a custom transport
+ # instance provides an extensibility point for unusual situations.
+ if isinstance(transport, SchemaServiceTransport):
+ # transport is a SchemaServiceTransport instance.
+ if credentials or client_options.credentials_file or api_key_value:
+ raise ValueError(
+ "When providing a transport instance, "
+ "provide its credentials directly."
+ )
+ if client_options.scopes:
+ raise ValueError(
+ "When providing a transport instance, provide its scopes "
+ "directly."
+ )
+ self._transport = transport
+ else:
+ import google.auth._default # type: ignore
+
+ if api_key_value and hasattr(
+ google.auth._default, "get_api_key_credentials"
+ ):
+ credentials = google.auth._default.get_api_key_credentials(
+ api_key_value
+ )
+
+ Transport = type(self).get_transport_class(transport)
+
+ emulator_host = os.environ.get("PUBSUB_EMULATOR_HOST")
+ if emulator_host:
+ if issubclass(Transport, type(self)._transport_registry["grpc"]):
+ channel = grpc.insecure_channel(target=emulator_host)
+ else:
+ channel = grpc.aio.insecure_channel(target=emulator_host)
+ Transport = functools.partial(Transport, channel=channel)
+
+ self._transport = Transport(
+ credentials=credentials,
+ credentials_file=client_options.credentials_file,
+ host=api_endpoint,
+ scopes=client_options.scopes,
+ client_cert_source_for_mtls=client_cert_source_func,
+ quota_project_id=client_options.quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=True,
+ api_audience=client_options.api_audience,
+ )
+
+ def create_schema(
+ self,
+ request: Union[gp_schema.CreateSchemaRequest, dict] = None,
+ *,
+ parent: str = None,
+ schema: gp_schema.Schema = None,
+ schema_id: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> gp_schema.Schema:
+ r"""Creates a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_create_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceClient()
+
+ # Initialize request argument(s)
+ schema = pubsub_v1.Schema()
+ schema.name = "name_value"
+
+ request = pubsub_v1.CreateSchemaRequest(
+ parent="parent_value",
+ schema=schema,
+ )
+
+ # Make the request
+ response = client.create_schema(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.CreateSchemaRequest, dict]):
+ The request object. Request for the CreateSchema method.
+ parent (str):
+ Required. The name of the project in which to create the
+ schema. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``parent`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ schema (google.pubsub_v1.types.Schema):
+ Required. The schema object to create.
+
+ This schema's ``name`` parameter is ignored. The schema
+ object returned by CreateSchema will have a ``name``
+ made using the given ``parent`` and ``schema_id``.
+
+ This corresponds to the ``schema`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ schema_id (str):
+ The ID to use for the schema, which will become the
+ final component of the schema's resource name.
+
+ See
+ https://cloud.google.com/pubsub/docs/admin#resource_names
+ for resource name constraints.
+
+ This corresponds to the ``schema_id`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Schema:
+ A schema resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([parent, schema, schema_id])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a gp_schema.CreateSchemaRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, gp_schema.CreateSchemaRequest):
+ request = gp_schema.CreateSchemaRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if parent is not None:
+ request.parent = parent
+ if schema is not None:
+ request.schema = schema
+ if schema_id is not None:
+ request.schema_id = schema_id
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.create_schema]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def get_schema(
+ self,
+ request: Union[schema.GetSchemaRequest, dict] = None,
+ *,
+ name: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> schema.Schema:
+ r"""Gets a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_get_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetSchemaRequest(
+ name="name_value",
+ )
+
+ # Make the request
+ response = client.get_schema(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetSchemaRequest, dict]):
+ The request object. Request for the GetSchema method.
+ name (str):
+ Required. The name of the schema to get. Format is
+ ``projects/{project}/schemas/{schema}``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Schema:
+ A schema resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a schema.GetSchemaRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, schema.GetSchemaRequest):
+ request = schema.GetSchemaRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.get_schema]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def list_schemas(
+ self,
+ request: Union[schema.ListSchemasRequest, dict] = None,
+ *,
+ parent: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListSchemasPager:
+ r"""Lists schemas in a project.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_list_schemas():
+ # Create a client
+ client = pubsub_v1.SchemaServiceClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListSchemasRequest(
+ parent="parent_value",
+ )
+
+ # Make the request
+ page_result = client.list_schemas(request=request)
+
+ # Handle the response
+ for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListSchemasRequest, dict]):
+ The request object. Request for the `ListSchemas`
+ method.
+ parent (str):
+ Required. The name of the project in which to list
+ schemas. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``parent`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.schema_service.pagers.ListSchemasPager:
+ Response for the ListSchemas method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([parent])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a schema.ListSchemasRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, schema.ListSchemasRequest):
+ request = schema.ListSchemasRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if parent is not None:
+ request.parent = parent
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_schemas]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__iter__` convenience method.
+ response = pagers.ListSchemasPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def delete_schema(
+ self,
+ request: Union[schema.DeleteSchemaRequest, dict] = None,
+ *,
+ name: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Deletes a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_delete_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteSchemaRequest(
+ name="name_value",
+ )
+
+ # Make the request
+ client.delete_schema(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteSchemaRequest, dict]):
+ The request object. Request for the `DeleteSchema`
+ method.
+ name (str):
+ Required. Name of the schema to delete. Format is
+ ``projects/{project}/schemas/{schema}``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a schema.DeleteSchemaRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, schema.DeleteSchemaRequest):
+ request = schema.DeleteSchemaRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.delete_schema]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ def validate_schema(
+ self,
+ request: Union[gp_schema.ValidateSchemaRequest, dict] = None,
+ *,
+ parent: str = None,
+ schema: gp_schema.Schema = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> gp_schema.ValidateSchemaResponse:
+ r"""Validates a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_validate_schema():
+ # Create a client
+ client = pubsub_v1.SchemaServiceClient()
+
+ # Initialize request argument(s)
+ schema = pubsub_v1.Schema()
+ schema.name = "name_value"
+
+ request = pubsub_v1.ValidateSchemaRequest(
+ parent="parent_value",
+ schema=schema,
+ )
+
+ # Make the request
+ response = client.validate_schema(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ValidateSchemaRequest, dict]):
+ The request object. Request for the `ValidateSchema`
+ method.
+ parent (str):
+ Required. The name of the project in which to validate
+ schemas. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``parent`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ schema (google.pubsub_v1.types.Schema):
+ Required. The schema object to
+ validate.
+
+ This corresponds to the ``schema`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.ValidateSchemaResponse:
+ Response for the ValidateSchema method.
+ Empty for now.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([parent, schema])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a gp_schema.ValidateSchemaRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, gp_schema.ValidateSchemaRequest):
+ request = gp_schema.ValidateSchemaRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if parent is not None:
+ request.parent = parent
+ if schema is not None:
+ request.schema = schema
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.validate_schema]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def validate_message(
+ self,
+ request: Union[schema.ValidateMessageRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> schema.ValidateMessageResponse:
+ r"""Validates a message against a schema.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_validate_message():
+ # Create a client
+ client = pubsub_v1.SchemaServiceClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ValidateMessageRequest(
+ name="name_value",
+ parent="parent_value",
+ )
+
+ # Make the request
+ response = client.validate_message(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ValidateMessageRequest, dict]):
+ The request object. Request for the `ValidateMessage`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.ValidateMessageResponse:
+ Response for the ValidateMessage method.
+ Empty for now.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Minor optimization to avoid making a copy if the user passes
+ # in a schema.ValidateMessageRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, schema.ValidateMessageRequest):
+ request = schema.ValidateMessageRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.validate_message]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("parent", request.parent),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, type, value, traceback):
+ """Releases underlying transport's resources.
+
+ .. warning::
+ ONLY use as a context manager if the transport is NOT shared
+ with other clients! Exiting the with block will CLOSE the transport
+ and may cause errors in other clients!
+ """
+ self.transport.close()
+
+ def set_iam_policy(
+ self,
+ request: iam_policy_pb2.SetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Sets the IAM access control policy on the specified function.
+
+ Replaces any existing policy.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.SetIamPolicyRequest`):
+ The request object. Request message for `SetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.SetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.set_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def get_iam_policy(
+ self,
+ request: iam_policy_pb2.GetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Gets the IAM access control policy for a function.
+
+ Returns an empty policy if the function exists and does not have a
+ policy set.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.GetIamPolicyRequest`):
+ The request object. Request message for `GetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if
+ any, should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.GetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.get_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def test_iam_permissions(
+ self,
+ request: iam_policy_pb2.TestIamPermissionsRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> iam_policy_pb2.TestIamPermissionsResponse:
+ r"""Tests the specified IAM permissions against the IAM access control
+ policy for a function.
+
+ If the function does not exist, this will return an empty set
+ of permissions, not a NOT_FOUND error.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.TestIamPermissionsRequest`):
+ The request object. Request message for
+ `TestIamPermissions` method.
+ retry (google.api_core.retry.Retry): Designation of what errors,
+ if any, should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.iam_policy_pb2.TestIamPermissionsResponse:
+ Response message for ``TestIamPermissions`` method.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.TestIamPermissionsRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.test_iam_permissions,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("SchemaServiceClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/pagers.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/pagers.py
new file mode 100644
index 000000000000..965778d459af
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/pagers.py
@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import (
+ Any,
+ AsyncIterator,
+ Awaitable,
+ Callable,
+ Sequence,
+ Tuple,
+ Optional,
+ Iterator,
+)
+
+from google.pubsub_v1.types import schema
+
+
+class ListSchemasPager:
+ """A pager for iterating through ``list_schemas`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListSchemasResponse` object, and
+ provides an ``__iter__`` method to iterate through its
+ ``schemas`` field.
+
+ If there are more pages, the ``__iter__`` method will make additional
+ ``ListSchemas`` requests and continue to iterate
+ through the ``schemas`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListSchemasResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., schema.ListSchemasResponse],
+ request: schema.ListSchemasRequest,
+ response: schema.ListSchemasResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiate the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListSchemasRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListSchemasResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = schema.ListSchemasRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ def pages(self) -> Iterator[schema.ListSchemasResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __iter__(self) -> Iterator[schema.Schema]:
+ for page in self.pages:
+ yield from page.schemas
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListSchemasAsyncPager:
+ """A pager for iterating through ``list_schemas`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListSchemasResponse` object, and
+ provides an ``__aiter__`` method to iterate through its
+ ``schemas`` field.
+
+ If there are more pages, the ``__aiter__`` method will make additional
+ ``ListSchemas`` requests and continue to iterate
+ through the ``schemas`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListSchemasResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., Awaitable[schema.ListSchemasResponse]],
+ request: schema.ListSchemasRequest,
+ response: schema.ListSchemasResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiates the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListSchemasRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListSchemasResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = schema.ListSchemasRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ async def pages(self) -> AsyncIterator[schema.ListSchemasResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = await self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __aiter__(self) -> AsyncIterator[schema.Schema]:
+ async def async_generator():
+ async for page in self.pages:
+ for response in page.schemas:
+ yield response
+
+ return async_generator()
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/__init__.py
new file mode 100644
index 000000000000..6c2d9460a073
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/__init__.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+from typing import Dict, Type
+
+from .base import SchemaServiceTransport
+from .grpc import SchemaServiceGrpcTransport
+from .grpc_asyncio import SchemaServiceGrpcAsyncIOTransport
+
+
+# Compile a registry of transports.
+_transport_registry = OrderedDict() # type: Dict[str, Type[SchemaServiceTransport]]
+_transport_registry["grpc"] = SchemaServiceGrpcTransport
+_transport_registry["grpc_asyncio"] = SchemaServiceGrpcAsyncIOTransport
+
+__all__ = (
+ "SchemaServiceTransport",
+ "SchemaServiceGrpcTransport",
+ "SchemaServiceGrpcAsyncIOTransport",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/base.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/base.py
new file mode 100644
index 000000000000..e2b5ad6608d4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/base.py
@@ -0,0 +1,270 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import abc
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Union
+import pkg_resources
+
+import google.auth # type: ignore
+import google.api_core
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import schema
+from google.pubsub_v1.types import schema as gp_schema
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+class SchemaServiceTransport(abc.ABC):
+ """Abstract transport class for SchemaService."""
+
+ AUTH_SCOPES = (
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/pubsub",
+ )
+
+ DEFAULT_HOST: str = "pubsub.googleapis.com"
+
+ def __init__(
+ self,
+ *,
+ host: str = DEFAULT_HOST,
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ **kwargs,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A list of scopes.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+ """
+
+ scopes_kwargs = {"scopes": scopes, "default_scopes": self.AUTH_SCOPES}
+
+ # Save the scopes.
+ self._scopes = scopes
+
+ # If no credentials are provided, then determine the appropriate
+ # defaults.
+ if credentials and credentials_file:
+ raise core_exceptions.DuplicateCredentialArgs(
+ "'credentials_file' and 'credentials' are mutually exclusive"
+ )
+
+ if credentials_file is not None:
+ credentials, _ = google.auth.load_credentials_from_file(
+ credentials_file, **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ elif credentials is None:
+ credentials, _ = google.auth.default(
+ **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ # Don't apply audience if the credentials file passed from user.
+ if hasattr(credentials, "with_gdch_audience"):
+ credentials = credentials.with_gdch_audience(
+ api_audience if api_audience else host
+ )
+
+ # If the credentials are service account credentials, then always try to use self signed JWT.
+ if (
+ always_use_jwt_access
+ and isinstance(credentials, service_account.Credentials)
+ and hasattr(service_account.Credentials, "with_always_use_jwt_access")
+ ):
+ credentials = credentials.with_always_use_jwt_access(True)
+
+ # Save the credentials.
+ self._credentials = credentials
+
+ # Save the hostname. Default to port 443 (HTTPS) if none is specified.
+ if ":" not in host:
+ host += ":443"
+ self._host = host
+
+ def _prep_wrapped_messages(self, client_info):
+ # Precompute the wrapped methods.
+ self._wrapped_methods = {
+ self.create_schema: gapic_v1.method.wrap_method(
+ self.create_schema,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ self.get_schema: gapic_v1.method.wrap_method(
+ self.get_schema,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ self.list_schemas: gapic_v1.method.wrap_method(
+ self.list_schemas,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ self.delete_schema: gapic_v1.method.wrap_method(
+ self.delete_schema,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ self.validate_schema: gapic_v1.method.wrap_method(
+ self.validate_schema,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ self.validate_message: gapic_v1.method.wrap_method(
+ self.validate_message,
+ default_timeout=None,
+ client_info=client_info,
+ ),
+ }
+
+ def close(self):
+ """Closes resources associated with the transport.
+
+ .. warning::
+ Only call this method if the transport is NOT shared
+ with other clients - this may cause errors in other clients!
+ """
+ raise NotImplementedError()
+
+ @property
+ def create_schema(
+ self,
+ ) -> Callable[
+ [gp_schema.CreateSchemaRequest],
+ Union[gp_schema.Schema, Awaitable[gp_schema.Schema]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def get_schema(
+ self,
+ ) -> Callable[
+ [schema.GetSchemaRequest], Union[schema.Schema, Awaitable[schema.Schema]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def list_schemas(
+ self,
+ ) -> Callable[
+ [schema.ListSchemasRequest],
+ Union[schema.ListSchemasResponse, Awaitable[schema.ListSchemasResponse]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def delete_schema(
+ self,
+ ) -> Callable[
+ [schema.DeleteSchemaRequest], Union[empty_pb2.Empty, Awaitable[empty_pb2.Empty]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def validate_schema(
+ self,
+ ) -> Callable[
+ [gp_schema.ValidateSchemaRequest],
+ Union[
+ gp_schema.ValidateSchemaResponse,
+ Awaitable[gp_schema.ValidateSchemaResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def validate_message(
+ self,
+ ) -> Callable[
+ [schema.ValidateMessageRequest],
+ Union[
+ schema.ValidateMessageResponse, Awaitable[schema.ValidateMessageResponse]
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.SetIamPolicyRequest],
+ Union[policy_pb2.Policy, Awaitable[policy_pb2.Policy]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.GetIamPolicyRequest],
+ Union[policy_pb2.Policy, Awaitable[policy_pb2.Policy]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ Union[
+ iam_policy_pb2.TestIamPermissionsResponse,
+ Awaitable[iam_policy_pb2.TestIamPermissionsResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def kind(self) -> str:
+ raise NotImplementedError()
+
+
+__all__ = ("SchemaServiceTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/grpc.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/grpc.py
new file mode 100644
index 000000000000..3fa0a5b12749
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/grpc.py
@@ -0,0 +1,478 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import warnings
+from typing import Callable, Dict, Optional, Sequence, Tuple, Union
+
+from google.api_core import grpc_helpers
+from google.api_core import gapic_v1
+import google.auth # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+
+import grpc # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import schema
+from google.pubsub_v1.types import schema as gp_schema
+from .base import SchemaServiceTransport, DEFAULT_CLIENT_INFO
+
+
+class SchemaServiceGrpcTransport(SchemaServiceTransport):
+ """gRPC backend transport for SchemaService.
+
+ Service for doing schema-related operations.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _stubs: Dict[str, Callable]
+
+ def __init__(
+ self,
+ *,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Sequence[str] = None,
+ channel: grpc.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional(Sequence[str])): A list of scopes. This argument is
+ ignored if ``channel`` is provided.
+ channel (Optional[grpc.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ("grpc.max_metadata_size", 4 * 1024 * 1024),
+ ("grpc.keepalive_time_ms", 30000),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> grpc.Channel:
+ """Create and return a gRPC channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ grpc.Channel: A gRPC channel object.
+
+ Raises:
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+
+ return grpc_helpers.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ @property
+ def grpc_channel(self) -> grpc.Channel:
+ """Return the channel designed to connect to this service."""
+ return self._grpc_channel
+
+ @property
+ def create_schema(
+ self,
+ ) -> Callable[[gp_schema.CreateSchemaRequest], gp_schema.Schema]:
+ r"""Return a callable for the create schema method over gRPC.
+
+ Creates a schema.
+
+ Returns:
+ Callable[[~.CreateSchemaRequest],
+ ~.Schema]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_schema" not in self._stubs:
+ self._stubs["create_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/CreateSchema",
+ request_serializer=gp_schema.CreateSchemaRequest.serialize,
+ response_deserializer=gp_schema.Schema.deserialize,
+ )
+ return self._stubs["create_schema"]
+
+ @property
+ def get_schema(self) -> Callable[[schema.GetSchemaRequest], schema.Schema]:
+ r"""Return a callable for the get schema method over gRPC.
+
+ Gets a schema.
+
+ Returns:
+ Callable[[~.GetSchemaRequest],
+ ~.Schema]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_schema" not in self._stubs:
+ self._stubs["get_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/GetSchema",
+ request_serializer=schema.GetSchemaRequest.serialize,
+ response_deserializer=schema.Schema.deserialize,
+ )
+ return self._stubs["get_schema"]
+
+ @property
+ def list_schemas(
+ self,
+ ) -> Callable[[schema.ListSchemasRequest], schema.ListSchemasResponse]:
+ r"""Return a callable for the list schemas method over gRPC.
+
+ Lists schemas in a project.
+
+ Returns:
+ Callable[[~.ListSchemasRequest],
+ ~.ListSchemasResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_schemas" not in self._stubs:
+ self._stubs["list_schemas"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/ListSchemas",
+ request_serializer=schema.ListSchemasRequest.serialize,
+ response_deserializer=schema.ListSchemasResponse.deserialize,
+ )
+ return self._stubs["list_schemas"]
+
+ @property
+ def delete_schema(self) -> Callable[[schema.DeleteSchemaRequest], empty_pb2.Empty]:
+ r"""Return a callable for the delete schema method over gRPC.
+
+ Deletes a schema.
+
+ Returns:
+ Callable[[~.DeleteSchemaRequest],
+ ~.Empty]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_schema" not in self._stubs:
+ self._stubs["delete_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/DeleteSchema",
+ request_serializer=schema.DeleteSchemaRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_schema"]
+
+ @property
+ def validate_schema(
+ self,
+ ) -> Callable[[gp_schema.ValidateSchemaRequest], gp_schema.ValidateSchemaResponse]:
+ r"""Return a callable for the validate schema method over gRPC.
+
+ Validates a schema.
+
+ Returns:
+ Callable[[~.ValidateSchemaRequest],
+ ~.ValidateSchemaResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "validate_schema" not in self._stubs:
+ self._stubs["validate_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/ValidateSchema",
+ request_serializer=gp_schema.ValidateSchemaRequest.serialize,
+ response_deserializer=gp_schema.ValidateSchemaResponse.deserialize,
+ )
+ return self._stubs["validate_schema"]
+
+ @property
+ def validate_message(
+ self,
+ ) -> Callable[[schema.ValidateMessageRequest], schema.ValidateMessageResponse]:
+ r"""Return a callable for the validate message method over gRPC.
+
+ Validates a message against a schema.
+
+ Returns:
+ Callable[[~.ValidateMessageRequest],
+ ~.ValidateMessageResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "validate_message" not in self._stubs:
+ self._stubs["validate_message"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/ValidateMessage",
+ request_serializer=schema.ValidateMessageRequest.serialize,
+ response_deserializer=schema.ValidateMessageResponse.deserialize,
+ )
+ return self._stubs["validate_message"]
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], policy_pb2.Policy]:
+ r"""Return a callable for the set iam policy method over gRPC.
+ Sets the IAM access control policy on the specified
+ function. Replaces any existing policy.
+ Returns:
+ Callable[[~.SetIamPolicyRequest],
+ ~.Policy]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "set_iam_policy" not in self._stubs:
+ self._stubs["set_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/SetIamPolicy",
+ request_serializer=iam_policy_pb2.SetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["set_iam_policy"]
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], policy_pb2.Policy]:
+ r"""Return a callable for the get iam policy method over gRPC.
+ Gets the IAM access control policy for a function.
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+ Returns:
+ Callable[[~.GetIamPolicyRequest],
+ ~.Policy]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_iam_policy" not in self._stubs:
+ self._stubs["get_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/GetIamPolicy",
+ request_serializer=iam_policy_pb2.GetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["get_iam_policy"]
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ iam_policy_pb2.TestIamPermissionsResponse,
+ ]:
+ r"""Return a callable for the test iam permissions method over gRPC.
+ Tests the specified permissions against the IAM access control
+ policy for a function. If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+ Returns:
+ Callable[[~.TestIamPermissionsRequest],
+ ~.TestIamPermissionsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "test_iam_permissions" not in self._stubs:
+ self._stubs["test_iam_permissions"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/TestIamPermissions",
+ request_serializer=iam_policy_pb2.TestIamPermissionsRequest.SerializeToString,
+ response_deserializer=iam_policy_pb2.TestIamPermissionsResponse.FromString,
+ )
+ return self._stubs["test_iam_permissions"]
+
+ def close(self):
+ self.grpc_channel.close()
+
+ @property
+ def kind(self) -> str:
+ return "grpc"
+
+
+__all__ = ("SchemaServiceGrpcTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/grpc_asyncio.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/grpc_asyncio.py
new file mode 100644
index 000000000000..fb89c89a2173
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/schema_service/transports/grpc_asyncio.py
@@ -0,0 +1,485 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import warnings
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Tuple, Union
+
+from google.api_core import gapic_v1
+from google.api_core import grpc_helpers_async
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+
+import grpc # type: ignore
+from grpc.experimental import aio # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import schema
+from google.pubsub_v1.types import schema as gp_schema
+from .base import SchemaServiceTransport, DEFAULT_CLIENT_INFO
+from .grpc import SchemaServiceGrpcTransport
+
+
+class SchemaServiceGrpcAsyncIOTransport(SchemaServiceTransport):
+ """gRPC AsyncIO backend transport for SchemaService.
+
+ Service for doing schema-related operations.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _grpc_channel: aio.Channel
+ _stubs: Dict[str, Callable] = {}
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> aio.Channel:
+ """Create and return a gRPC AsyncIO channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ aio.Channel: A gRPC AsyncIO channel object.
+ """
+
+ return grpc_helpers_async.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ def __init__(
+ self,
+ *,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ channel: aio.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id=None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ channel (Optional[aio.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ("grpc.max_metadata_size", 4 * 1024 * 1024),
+ ("grpc.keepalive_time_ms", 30000),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @property
+ def grpc_channel(self) -> aio.Channel:
+ """Create the channel designed to connect to this service.
+
+ This property caches on the instance; repeated calls return
+ the same channel.
+ """
+ # Return the channel from cache.
+ return self._grpc_channel
+
+ @property
+ def create_schema(
+ self,
+ ) -> Callable[[gp_schema.CreateSchemaRequest], Awaitable[gp_schema.Schema]]:
+ r"""Return a callable for the create schema method over gRPC.
+
+ Creates a schema.
+
+ Returns:
+ Callable[[~.CreateSchemaRequest],
+ Awaitable[~.Schema]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_schema" not in self._stubs:
+ self._stubs["create_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/CreateSchema",
+ request_serializer=gp_schema.CreateSchemaRequest.serialize,
+ response_deserializer=gp_schema.Schema.deserialize,
+ )
+ return self._stubs["create_schema"]
+
+ @property
+ def get_schema(
+ self,
+ ) -> Callable[[schema.GetSchemaRequest], Awaitable[schema.Schema]]:
+ r"""Return a callable for the get schema method over gRPC.
+
+ Gets a schema.
+
+ Returns:
+ Callable[[~.GetSchemaRequest],
+ Awaitable[~.Schema]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_schema" not in self._stubs:
+ self._stubs["get_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/GetSchema",
+ request_serializer=schema.GetSchemaRequest.serialize,
+ response_deserializer=schema.Schema.deserialize,
+ )
+ return self._stubs["get_schema"]
+
+ @property
+ def list_schemas(
+ self,
+ ) -> Callable[[schema.ListSchemasRequest], Awaitable[schema.ListSchemasResponse]]:
+ r"""Return a callable for the list schemas method over gRPC.
+
+ Lists schemas in a project.
+
+ Returns:
+ Callable[[~.ListSchemasRequest],
+ Awaitable[~.ListSchemasResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_schemas" not in self._stubs:
+ self._stubs["list_schemas"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/ListSchemas",
+ request_serializer=schema.ListSchemasRequest.serialize,
+ response_deserializer=schema.ListSchemasResponse.deserialize,
+ )
+ return self._stubs["list_schemas"]
+
+ @property
+ def delete_schema(
+ self,
+ ) -> Callable[[schema.DeleteSchemaRequest], Awaitable[empty_pb2.Empty]]:
+ r"""Return a callable for the delete schema method over gRPC.
+
+ Deletes a schema.
+
+ Returns:
+ Callable[[~.DeleteSchemaRequest],
+ Awaitable[~.Empty]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_schema" not in self._stubs:
+ self._stubs["delete_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/DeleteSchema",
+ request_serializer=schema.DeleteSchemaRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_schema"]
+
+ @property
+ def validate_schema(
+ self,
+ ) -> Callable[
+ [gp_schema.ValidateSchemaRequest], Awaitable[gp_schema.ValidateSchemaResponse]
+ ]:
+ r"""Return a callable for the validate schema method over gRPC.
+
+ Validates a schema.
+
+ Returns:
+ Callable[[~.ValidateSchemaRequest],
+ Awaitable[~.ValidateSchemaResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "validate_schema" not in self._stubs:
+ self._stubs["validate_schema"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/ValidateSchema",
+ request_serializer=gp_schema.ValidateSchemaRequest.serialize,
+ response_deserializer=gp_schema.ValidateSchemaResponse.deserialize,
+ )
+ return self._stubs["validate_schema"]
+
+ @property
+ def validate_message(
+ self,
+ ) -> Callable[
+ [schema.ValidateMessageRequest], Awaitable[schema.ValidateMessageResponse]
+ ]:
+ r"""Return a callable for the validate message method over gRPC.
+
+ Validates a message against a schema.
+
+ Returns:
+ Callable[[~.ValidateMessageRequest],
+ Awaitable[~.ValidateMessageResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "validate_message" not in self._stubs:
+ self._stubs["validate_message"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.SchemaService/ValidateMessage",
+ request_serializer=schema.ValidateMessageRequest.serialize,
+ response_deserializer=schema.ValidateMessageResponse.deserialize,
+ )
+ return self._stubs["validate_message"]
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], Awaitable[policy_pb2.Policy]]:
+ r"""Return a callable for the set iam policy method over gRPC.
+ Sets the IAM access control policy on the specified
+ function. Replaces any existing policy.
+ Returns:
+ Callable[[~.SetIamPolicyRequest],
+ Awaitable[~.Policy]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "set_iam_policy" not in self._stubs:
+ self._stubs["set_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/SetIamPolicy",
+ request_serializer=iam_policy_pb2.SetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["set_iam_policy"]
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], Awaitable[policy_pb2.Policy]]:
+ r"""Return a callable for the get iam policy method over gRPC.
+ Gets the IAM access control policy for a function.
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+ Returns:
+ Callable[[~.GetIamPolicyRequest],
+ Awaitable[~.Policy]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_iam_policy" not in self._stubs:
+ self._stubs["get_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/GetIamPolicy",
+ request_serializer=iam_policy_pb2.GetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["get_iam_policy"]
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ Awaitable[iam_policy_pb2.TestIamPermissionsResponse],
+ ]:
+ r"""Return a callable for the test iam permissions method over gRPC.
+ Tests the specified permissions against the IAM access control
+ policy for a function. If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+ Returns:
+ Callable[[~.TestIamPermissionsRequest],
+ Awaitable[~.TestIamPermissionsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "test_iam_permissions" not in self._stubs:
+ self._stubs["test_iam_permissions"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/TestIamPermissions",
+ request_serializer=iam_policy_pb2.TestIamPermissionsRequest.SerializeToString,
+ response_deserializer=iam_policy_pb2.TestIamPermissionsResponse.FromString,
+ )
+ return self._stubs["test_iam_permissions"]
+
+ def close(self):
+ return self.grpc_channel.close()
+
+
+__all__ = ("SchemaServiceGrpcAsyncIOTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/__init__.py
new file mode 100644
index 000000000000..1d7599467227
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/__init__.py
@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from .client import SubscriberClient
+from .async_client import SubscriberAsyncClient
+
+__all__ = (
+ "SubscriberClient",
+ "SubscriberAsyncClient",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/async_client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/async_client.py
new file mode 100644
index 000000000000..902d134c632c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/async_client.py
@@ -0,0 +1,2517 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import functools
+import re
+from typing import (
+ Dict,
+ Mapping,
+ Optional,
+ AsyncIterable,
+ Awaitable,
+ AsyncIterator,
+ Sequence,
+ Tuple,
+ Type,
+ Union,
+)
+import warnings
+import pkg_resources
+
+from google.api_core.client_options import ClientOptions
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import duration_pb2 # type: ignore
+from google.protobuf import timestamp_pb2 # type: ignore
+from google.pubsub_v1.services.subscriber import pagers
+from google.pubsub_v1.types import pubsub
+from .transports.base import SubscriberTransport, DEFAULT_CLIENT_INFO
+from .transports.grpc_asyncio import SubscriberGrpcAsyncIOTransport
+from .client import SubscriberClient
+
+
+class SubscriberAsyncClient:
+ """The service that an application uses to manipulate subscriptions and
+ to consume messages from a subscription via the ``Pull`` method or
+ by establishing a bi-directional stream using the ``StreamingPull``
+ method.
+ """
+
+ _client: SubscriberClient
+
+ DEFAULT_ENDPOINT = SubscriberClient.DEFAULT_ENDPOINT
+ DEFAULT_MTLS_ENDPOINT = SubscriberClient.DEFAULT_MTLS_ENDPOINT
+
+ snapshot_path = staticmethod(SubscriberClient.snapshot_path)
+ parse_snapshot_path = staticmethod(SubscriberClient.parse_snapshot_path)
+ subscription_path = staticmethod(SubscriberClient.subscription_path)
+ parse_subscription_path = staticmethod(SubscriberClient.parse_subscription_path)
+ topic_path = staticmethod(SubscriberClient.topic_path)
+ parse_topic_path = staticmethod(SubscriberClient.parse_topic_path)
+ common_billing_account_path = staticmethod(
+ SubscriberClient.common_billing_account_path
+ )
+ parse_common_billing_account_path = staticmethod(
+ SubscriberClient.parse_common_billing_account_path
+ )
+ common_folder_path = staticmethod(SubscriberClient.common_folder_path)
+ parse_common_folder_path = staticmethod(SubscriberClient.parse_common_folder_path)
+ common_organization_path = staticmethod(SubscriberClient.common_organization_path)
+ parse_common_organization_path = staticmethod(
+ SubscriberClient.parse_common_organization_path
+ )
+ common_project_path = staticmethod(SubscriberClient.common_project_path)
+ parse_common_project_path = staticmethod(SubscriberClient.parse_common_project_path)
+ common_location_path = staticmethod(SubscriberClient.common_location_path)
+ parse_common_location_path = staticmethod(
+ SubscriberClient.parse_common_location_path
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SubscriberAsyncClient: The constructed client.
+ """
+ return SubscriberClient.from_service_account_info.__func__(SubscriberAsyncClient, info, *args, **kwargs) # type: ignore
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SubscriberAsyncClient: The constructed client.
+ """
+ return SubscriberClient.from_service_account_file.__func__(SubscriberAsyncClient, filename, *args, **kwargs) # type: ignore
+
+ from_service_account_json = from_service_account_file
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ return SubscriberClient.get_mtls_endpoint_and_cert_source(client_options) # type: ignore
+
+ @property
+ def transport(self) -> SubscriberTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ SubscriberTransport: The transport used by the client instance.
+ """
+ return self._client.transport
+
+ get_transport_class = functools.partial(
+ type(SubscriberClient).get_transport_class, type(SubscriberClient)
+ )
+
+ def __init__(
+ self,
+ *,
+ credentials: ga_credentials.Credentials = None,
+ transport: Union[str, SubscriberTransport] = "grpc_asyncio",
+ client_options: ClientOptions = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the subscriber client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, ~.SubscriberTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (ClientOptions): Custom options for the client. It
+ won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ self._client = SubscriberClient(
+ credentials=credentials,
+ transport=transport,
+ client_options=client_options,
+ client_info=client_info,
+ )
+
+ async def create_subscription(
+ self,
+ request: Union[pubsub.Subscription, dict] = None,
+ *,
+ name: str = None,
+ topic: str = None,
+ push_config: pubsub.PushConfig = None,
+ ack_deadline_seconds: int = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Subscription:
+ r"""Creates a subscription to a given topic. See the [resource name
+ rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). If
+ the subscription already exists, returns ``ALREADY_EXISTS``. If
+ the corresponding topic doesn't exist, returns ``NOT_FOUND``.
+
+ If the name is not provided in the request, the server will
+ assign a random name for this subscription on the same project
+ as the topic, conforming to the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Subscription object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_create_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.Subscription(
+ name="name_value",
+ topic="topic_value",
+ )
+
+ # Make the request
+ response = await client.create_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.Subscription, dict]):
+ The request object. A subscription resource.
+ name (:class:`str`):
+ Required. The name of the subscription. It must have the
+ format
+ ``"projects/{project}/subscriptions/{subscription}"``.
+ ``{subscription}`` must start with a letter, and contain
+ only letters (``[A-Za-z]``), numbers (``[0-9]``), dashes
+ (``-``), underscores (``_``), periods (``.``), tildes
+ (``~``), plus (``+``) or percent signs (``%``). It must
+ be between 3 and 255 characters in length, and it must
+ not start with ``"goog"``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ topic (:class:`str`):
+ Required. The name of the topic from which this
+ subscription is receiving messages. Format is
+ ``projects/{project}/topics/{topic}``. The value of this
+ field will be ``_deleted-topic_`` if the topic has been
+ deleted.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ push_config (:class:`google.pubsub_v1.types.PushConfig`):
+ If push delivery is used with this subscription, this
+ field is used to configure it. Either ``pushConfig`` or
+ ``bigQueryConfig`` can be set, but not both. If both are
+ empty, then the subscriber will pull and ack messages
+ using API methods.
+
+ This corresponds to the ``push_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_deadline_seconds (:class:`int`):
+ The approximate amount of time (on a best-effort basis)
+ Pub/Sub waits for the subscriber to acknowledge receipt
+ before resending the message. In the interval after the
+ message is delivered and before it is acknowledged, it
+ is considered to be outstanding. During that time
+ period, the message will not be redelivered (on a
+ best-effort basis).
+
+ For pull subscriptions, this value is used as the
+ initial value for the ack deadline. To override this
+ value for a given message, call ``ModifyAckDeadline``
+ with the corresponding ``ack_id`` if using non-streaming
+ pull or send the ``ack_id`` in a
+ ``StreamingModifyAckDeadlineRequest`` if using streaming
+ pull. The minimum custom deadline you can specify is 10
+ seconds. The maximum custom deadline you can specify is
+ 600 seconds (10 minutes). If this parameter is 0, a
+ default value of 10 seconds is used.
+
+ For push delivery, this value is also used to set the
+ request timeout for the call to the push endpoint.
+
+ If the subscriber never acknowledges the message, the
+ Pub/Sub system will eventually redeliver the message.
+
+ This corresponds to the ``ack_deadline_seconds`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Subscription:
+ A subscription resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name, topic, push_config, ack_deadline_seconds])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.Subscription(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+ if topic is not None:
+ request.topic = topic
+ if push_config is not None:
+ request.push_config = push_config
+ if ack_deadline_seconds is not None:
+ request.ack_deadline_seconds = ack_deadline_seconds
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.create_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def get_subscription(
+ self,
+ request: Union[pubsub.GetSubscriptionRequest, dict] = None,
+ *,
+ subscription: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Subscription:
+ r"""Gets the configuration details of a subscription.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_get_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetSubscriptionRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = await client.get_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetSubscriptionRequest, dict]):
+ The request object. Request for the GetSubscription
+ method.
+ subscription (:class:`str`):
+ Required. The name of the subscription to get. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Subscription:
+ A subscription resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.GetSubscriptionRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.get_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def update_subscription(
+ self,
+ request: Union[pubsub.UpdateSubscriptionRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Subscription:
+ r"""Updates an existing subscription. Note that certain
+ properties of a subscription, such as its topic, are not
+ modifiable.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_update_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ subscription = pubsub_v1.Subscription()
+ subscription.name = "name_value"
+ subscription.topic = "topic_value"
+
+ request = pubsub_v1.UpdateSubscriptionRequest(
+ subscription=subscription,
+ )
+
+ # Make the request
+ response = await client.update_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.UpdateSubscriptionRequest, dict]):
+ The request object. Request for the UpdateSubscription
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Subscription:
+ A subscription resource.
+ """
+ # Create or coerce a protobuf request object.
+ request = pubsub.UpdateSubscriptionRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.update_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription.name", request.subscription.name),)
+ ),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def list_subscriptions(
+ self,
+ request: Union[pubsub.ListSubscriptionsRequest, dict] = None,
+ *,
+ project: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListSubscriptionsAsyncPager:
+ r"""Lists matching subscriptions.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_list_subscriptions():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListSubscriptionsRequest(
+ project="project_value",
+ )
+
+ # Make the request
+ page_result = client.list_subscriptions(request=request)
+
+ # Handle the response
+ async for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListSubscriptionsRequest, dict]):
+ The request object. Request for the `ListSubscriptions`
+ method.
+ project (:class:`str`):
+ Required. The name of the project in which to list
+ subscriptions. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``project`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager:
+ Response for the ListSubscriptions method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([project])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.ListSubscriptionsRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if project is not None:
+ request.project = project
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_subscriptions,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__aiter__` convenience method.
+ response = pagers.ListSubscriptionsAsyncPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def delete_subscription(
+ self,
+ request: Union[pubsub.DeleteSubscriptionRequest, dict] = None,
+ *,
+ subscription: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Deletes an existing subscription. All messages retained in the
+ subscription are immediately dropped. Calls to ``Pull`` after
+ deletion will return ``NOT_FOUND``. After a subscription is
+ deleted, a new one may be created with the same name, but the
+ new one has no association with the old subscription or its
+ topic unless the same topic is specified.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_delete_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteSubscriptionRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ await client.delete_subscription(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteSubscriptionRequest, dict]):
+ The request object. Request for the DeleteSubscription
+ method.
+ subscription (:class:`str`):
+ Required. The subscription to delete. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.DeleteSubscriptionRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.delete_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ async def modify_ack_deadline(
+ self,
+ request: Union[pubsub.ModifyAckDeadlineRequest, dict] = None,
+ *,
+ subscription: str = None,
+ ack_ids: Sequence[str] = None,
+ ack_deadline_seconds: int = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Modifies the ack deadline for a specific message. This method is
+ useful to indicate that more time is needed to process a message
+ by the subscriber, or to make the message available for
+ redelivery if the processing was interrupted. Note that this
+ does not modify the subscription-level ``ackDeadlineSeconds``
+ used for subsequent messages.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_modify_ack_deadline():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ModifyAckDeadlineRequest(
+ subscription="subscription_value",
+ ack_ids=['ack_ids_value1', 'ack_ids_value2'],
+ ack_deadline_seconds=2066,
+ )
+
+ # Make the request
+ await client.modify_ack_deadline(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ModifyAckDeadlineRequest, dict]):
+ The request object. Request for the ModifyAckDeadline
+ method.
+ subscription (:class:`str`):
+ Required. The name of the subscription. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_ids (:class:`Sequence[str]`):
+ Required. List of acknowledgment IDs.
+ This corresponds to the ``ack_ids`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_deadline_seconds (:class:`int`):
+ Required. The new ack deadline with respect to the time
+ this request was sent to the Pub/Sub system. For
+ example, if the value is 10, the new ack deadline will
+ expire 10 seconds after the ``ModifyAckDeadline`` call
+ was made. Specifying zero might immediately make the
+ message available for delivery to another subscriber
+ client. This typically results in an increase in the
+ rate of message redeliveries (that is, duplicates). The
+ minimum deadline you can specify is 0 seconds. The
+ maximum deadline you can specify is 600 seconds (10
+ minutes).
+
+ This corresponds to the ``ack_deadline_seconds`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, ack_ids, ack_deadline_seconds])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.ModifyAckDeadlineRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if ack_deadline_seconds is not None:
+ request.ack_deadline_seconds = ack_deadline_seconds
+ if ack_ids:
+ request.ack_ids.extend(ack_ids)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.modify_ack_deadline,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ async def acknowledge(
+ self,
+ request: Union[pubsub.AcknowledgeRequest, dict] = None,
+ *,
+ subscription: str = None,
+ ack_ids: Sequence[str] = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Acknowledges the messages associated with the ``ack_ids`` in the
+ ``AcknowledgeRequest``. The Pub/Sub system can remove the
+ relevant messages from the subscription.
+
+ Acknowledging a message whose ack deadline has expired may
+ succeed, but such a message may be redelivered later.
+ Acknowledging a message more than once will not result in an
+ error.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_acknowledge():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.AcknowledgeRequest(
+ subscription="subscription_value",
+ ack_ids=['ack_ids_value1', 'ack_ids_value2'],
+ )
+
+ # Make the request
+ await client.acknowledge(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.AcknowledgeRequest, dict]):
+ The request object. Request for the Acknowledge method.
+ subscription (:class:`str`):
+ Required. The subscription whose message is being
+ acknowledged. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_ids (:class:`Sequence[str]`):
+ Required. The acknowledgment ID for the messages being
+ acknowledged that was returned by the Pub/Sub system in
+ the ``Pull`` response. Must not be empty.
+
+ This corresponds to the ``ack_ids`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, ack_ids])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.AcknowledgeRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if ack_ids:
+ request.ack_ids.extend(ack_ids)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.acknowledge,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ async def pull(
+ self,
+ request: Union[pubsub.PullRequest, dict] = None,
+ *,
+ subscription: str = None,
+ return_immediately: bool = None,
+ max_messages: int = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.PullResponse:
+ r"""Pulls messages from the server. The server may return
+ ``UNAVAILABLE`` if there are too many concurrent pull requests
+ pending for the given subscription.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_pull():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.PullRequest(
+ subscription="subscription_value",
+ max_messages=1277,
+ )
+
+ # Make the request
+ response = await client.pull(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.PullRequest, dict]):
+ The request object. Request for the `Pull` method.
+ subscription (:class:`str`):
+ Required. The subscription from which messages should be
+ pulled. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ return_immediately (:class:`bool`):
+ Optional. If this field set to true, the system will
+ respond immediately even if it there are no messages
+ available to return in the ``Pull`` response. Otherwise,
+ the system may wait (for a bounded amount of time) until
+ at least one message is available, rather than returning
+ no messages. Warning: setting this field to ``true`` is
+ discouraged because it adversely impacts the performance
+ of ``Pull`` operations. We recommend that users do not
+ set this field.
+
+ This corresponds to the ``return_immediately`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ max_messages (:class:`int`):
+ Required. The maximum number of
+ messages to return for this request.
+ Must be a positive integer. The Pub/Sub
+ system may return fewer than the number
+ specified.
+
+ This corresponds to the ``max_messages`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.PullResponse:
+ Response for the Pull method.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, return_immediately, max_messages])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.PullRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if return_immediately is not None:
+ request.return_immediately = return_immediately
+ if max_messages is not None:
+ request.max_messages = max_messages
+
+ if request.return_immediately:
+ warnings.warn(
+ "The return_immediately flag is deprecated and should be set to False.",
+ category=DeprecationWarning,
+ )
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.pull,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def streaming_pull(
+ self,
+ requests: AsyncIterator[pubsub.StreamingPullRequest] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> Awaitable[AsyncIterable[pubsub.StreamingPullResponse]]:
+ r"""Establishes a stream with the server, which sends messages down
+ to the client. The client streams acknowledgements and ack
+ deadline modifications back to the server. The server will close
+ the stream and return the status on any error. The server may
+ close the stream with status ``UNAVAILABLE`` to reassign
+ server-side resources, in which case, the client should
+ re-establish the stream. Flow control can be achieved by
+ configuring the underlying RPC channel.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_streaming_pull():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.StreamingPullRequest(
+ subscription="subscription_value",
+ stream_ack_deadline_seconds=2813,
+ )
+
+ # This method expects an iterator which contains
+ # 'pubsub_v1.StreamingPullRequest' objects
+ # Here we create a generator that yields a single `request` for
+ # demonstrative purposes.
+ requests = [request]
+
+ def request_generator():
+ for request in requests:
+ yield request
+
+ # Make the request
+ stream = await client.streaming_pull(requests=request_generator())
+
+ # Handle the response
+ async for response in stream:
+ print(response)
+
+ Args:
+ requests (AsyncIterator[`google.pubsub_v1.types.StreamingPullRequest`]):
+ The request object AsyncIterator. Request for the `StreamingPull`
+ streaming RPC method. This request is used to establish
+ the initial stream as well as to stream acknowledgements
+ and ack deadline modifications from the client to the
+ server.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ AsyncIterable[google.pubsub_v1.types.StreamingPullResponse]:
+ Response for the StreamingPull method. This response is used to stream
+ messages from the server to the client.
+
+ """
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.streaming_pull,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.DeadlineExceeded,
+ core_exceptions.InternalServerError,
+ core_exceptions.ResourceExhausted,
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=900.0,
+ ),
+ default_timeout=900.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Send the request.
+ response = rpc(
+ requests,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def modify_push_config(
+ self,
+ request: Union[pubsub.ModifyPushConfigRequest, dict] = None,
+ *,
+ subscription: str = None,
+ push_config: pubsub.PushConfig = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Modifies the ``PushConfig`` for a specified subscription.
+
+ This may be used to change a push subscription to a pull one
+ (signified by an empty ``PushConfig``) or vice versa, or change
+ the endpoint URL and other attributes of a push subscription.
+ Messages will accumulate for delivery continuously through the
+ call regardless of changes to the ``PushConfig``.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_modify_push_config():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ModifyPushConfigRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ await client.modify_push_config(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ModifyPushConfigRequest, dict]):
+ The request object. Request for the ModifyPushConfig
+ method.
+ subscription (:class:`str`):
+ Required. The name of the subscription. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ push_config (:class:`google.pubsub_v1.types.PushConfig`):
+ Required. The push configuration for future deliveries.
+
+ An empty ``pushConfig`` indicates that the Pub/Sub
+ system should stop pushing messages from the given
+ subscription and allow messages to be pulled and
+ acknowledged - effectively pausing the subscription if
+ ``Pull`` or ``StreamingPull`` is not called.
+
+ This corresponds to the ``push_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, push_config])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.ModifyPushConfigRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if push_config is not None:
+ request.push_config = push_config
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.modify_push_config,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ async def get_snapshot(
+ self,
+ request: Union[pubsub.GetSnapshotRequest, dict] = None,
+ *,
+ snapshot: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Snapshot:
+ r"""Gets the configuration details of a snapshot.
+ Snapshots are used in Seek
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_get_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetSnapshotRequest(
+ snapshot="snapshot_value",
+ )
+
+ # Make the request
+ response = await client.get_snapshot(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetSnapshotRequest, dict]):
+ The request object. Request for the GetSnapshot method.
+ snapshot (:class:`str`):
+ Required. The name of the snapshot to get. Format is
+ ``projects/{project}/snapshots/{snap}``.
+
+ This corresponds to the ``snapshot`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Snapshot:
+ A snapshot resource. Snapshots are used in
+ [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([snapshot])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.GetSnapshotRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if snapshot is not None:
+ request.snapshot = snapshot
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.get_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("snapshot", request.snapshot),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def list_snapshots(
+ self,
+ request: Union[pubsub.ListSnapshotsRequest, dict] = None,
+ *,
+ project: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListSnapshotsAsyncPager:
+ r"""Lists the existing snapshots. Snapshots are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_list_snapshots():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListSnapshotsRequest(
+ project="project_value",
+ )
+
+ # Make the request
+ page_result = client.list_snapshots(request=request)
+
+ # Handle the response
+ async for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListSnapshotsRequest, dict]):
+ The request object. Request for the `ListSnapshots`
+ method.
+ project (:class:`str`):
+ Required. The name of the project in which to list
+ snapshots. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``project`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager:
+ Response for the ListSnapshots method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([project])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.ListSnapshotsRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if project is not None:
+ request.project = project
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.list_snapshots,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__aiter__` convenience method.
+ response = pagers.ListSnapshotsAsyncPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def create_snapshot(
+ self,
+ request: Union[pubsub.CreateSnapshotRequest, dict] = None,
+ *,
+ name: str = None,
+ subscription: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Snapshot:
+ r"""Creates a snapshot from the requested subscription. Snapshots
+ are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ If the snapshot already exists, returns ``ALREADY_EXISTS``. If
+ the requested subscription doesn't exist, returns ``NOT_FOUND``.
+ If the backlog in the subscription is too old -- and the
+ resulting snapshot would expire in less than 1 hour -- then
+ ``FAILED_PRECONDITION`` is returned. See also the
+ ``Snapshot.expire_time`` field. If the name is not provided in
+ the request, the server will assign a random name for this
+ snapshot on the same project as the subscription, conforming to
+ the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Snapshot object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_create_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.CreateSnapshotRequest(
+ name="name_value",
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = await client.create_snapshot(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.CreateSnapshotRequest, dict]):
+ The request object. Request for the `CreateSnapshot`
+ method.
+ name (:class:`str`):
+ Required. User-provided name for this snapshot. If the
+ name is not provided in the request, the server will
+ assign a random name for this snapshot on the same
+ project as the subscription. Note that for REST API
+ requests, you must specify a name. See the resource name
+ rules. Format is
+ ``projects/{project}/snapshots/{snap}``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ subscription (:class:`str`):
+ Required. The subscription whose backlog the snapshot
+ retains. Specifically, the created snapshot is
+ guaranteed to retain: (a) The existing backlog on the
+ subscription. More precisely, this is defined as the
+ messages in the subscription's backlog that are
+ unacknowledged upon the successful completion of the
+ ``CreateSnapshot`` request; as well as: (b) Any messages
+ published to the subscription's topic following the
+ successful completion of the CreateSnapshot request.
+ Format is ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Snapshot:
+ A snapshot resource. Snapshots are used in
+ [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name, subscription])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.CreateSnapshotRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+ if subscription is not None:
+ request.subscription = subscription
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.create_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def update_snapshot(
+ self,
+ request: Union[pubsub.UpdateSnapshotRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Snapshot:
+ r"""Updates an existing snapshot. Snapshots are used in
+ Seek
+ operations, which allow
+ you to manage message acknowledgments in bulk. That is,
+ you can set the acknowledgment state of messages in an
+ existing subscription to the state captured by a
+ snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_update_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.UpdateSnapshotRequest(
+ )
+
+ # Make the request
+ response = await client.update_snapshot(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.UpdateSnapshotRequest, dict]):
+ The request object. Request for the UpdateSnapshot
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Snapshot:
+ A snapshot resource. Snapshots are used in
+ [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ """
+ # Create or coerce a protobuf request object.
+ request = pubsub.UpdateSnapshotRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.update_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("snapshot.name", request.snapshot.name),)
+ ),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def delete_snapshot(
+ self,
+ request: Union[pubsub.DeleteSnapshotRequest, dict] = None,
+ *,
+ snapshot: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Removes an existing snapshot. Snapshots are used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ When the snapshot is deleted, all messages retained in the
+ snapshot are immediately dropped. After a snapshot is deleted, a
+ new one may be created with the same name, but the new one has
+ no association with the old snapshot or its subscription, unless
+ the same subscription is specified.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_delete_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteSnapshotRequest(
+ snapshot="snapshot_value",
+ )
+
+ # Make the request
+ await client.delete_snapshot(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteSnapshotRequest, dict]):
+ The request object. Request for the `DeleteSnapshot`
+ method.
+ snapshot (:class:`str`):
+ Required. The name of the snapshot to delete. Format is
+ ``projects/{project}/snapshots/{snap}``.
+
+ This corresponds to the ``snapshot`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([snapshot])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ request = pubsub.DeleteSnapshotRequest(request)
+
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if snapshot is not None:
+ request.snapshot = snapshot
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.delete_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("snapshot", request.snapshot),)),
+ )
+
+ # Send the request.
+ await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ async def seek(
+ self,
+ request: Union[pubsub.SeekRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.SeekResponse:
+ r"""Seeks an existing subscription to a point in time or to a given
+ snapshot, whichever is provided in the request. Snapshots are
+ used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ Note that both the subscription and the snapshot must be on the
+ same topic.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ async def sample_seek():
+ # Create a client
+ client = pubsub_v1.SubscriberAsyncClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.SeekRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = await client.seek(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.SeekRequest, dict]):
+ The request object. Request for the `Seek` method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.SeekResponse:
+ Response for the Seek method (this response is empty).
+ """
+ # Create or coerce a protobuf request object.
+ request = pubsub.SeekRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.seek,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def set_iam_policy(
+ self,
+ request: iam_policy_pb2.SetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Sets the IAM access control policy on the specified function.
+
+ Replaces any existing policy.
+
+ Args:
+ request (:class:`~.policy_pb2.SetIamPolicyRequest`):
+ The request object. Request message for `SetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.SetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.set_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def get_iam_policy(
+ self,
+ request: iam_policy_pb2.GetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Gets the IAM access control policy for a function.
+
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.GetIamPolicyRequest`):
+ The request object. Request message for `GetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.GetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.get_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def test_iam_permissions(
+ self,
+ request: iam_policy_pb2.TestIamPermissionsRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> iam_policy_pb2.TestIamPermissionsResponse:
+ r"""Tests the specified permissions against the IAM access control
+ policy for a function.
+
+ If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.TestIamPermissionsRequest`):
+ The request object. Request message for
+ `TestIamPermissions` method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~iam_policy_pb2.PolicyTestIamPermissionsResponse:
+ Response message for ``TestIamPermissions`` method.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.TestIamPermissionsRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method_async.wrap_method(
+ self._client._transport.test_iam_permissions,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = await rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb):
+ await self.transport.close()
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("SubscriberAsyncClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
new file mode 100644
index 000000000000..6f08e2792e1a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
@@ -0,0 +1,2644 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+import functools
+import os
+import re
+from typing import (
+ Dict,
+ Mapping,
+ Optional,
+ Iterable,
+ Iterator,
+ Sequence,
+ Tuple,
+ Type,
+ Union,
+)
+import warnings
+import pkg_resources
+
+from google.api_core import client_options as client_options_lib
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport import mtls # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+from google.auth.exceptions import MutualTLSChannelError # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+try:
+ OptionalRetry = Union[retries.Retry, gapic_v1.method._MethodDefault]
+except AttributeError: # pragma: NO COVER
+ OptionalRetry = Union[retries.Retry, object] # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import duration_pb2 # type: ignore
+from google.protobuf import timestamp_pb2 # type: ignore
+from google.pubsub_v1.services.subscriber import pagers
+from google.pubsub_v1.types import pubsub
+
+import grpc
+from .transports.base import SubscriberTransport, DEFAULT_CLIENT_INFO
+from .transports.grpc import SubscriberGrpcTransport
+from .transports.grpc_asyncio import SubscriberGrpcAsyncIOTransport
+
+
+class SubscriberClientMeta(type):
+ """Metaclass for the Subscriber client.
+
+ This provides class-level methods for building and retrieving
+ support objects (e.g. transport) without polluting the client instance
+ objects.
+ """
+
+ _transport_registry = OrderedDict() # type: Dict[str, Type[SubscriberTransport]]
+ _transport_registry["grpc"] = SubscriberGrpcTransport
+ _transport_registry["grpc_asyncio"] = SubscriberGrpcAsyncIOTransport
+
+ def get_transport_class(
+ cls,
+ label: str = None,
+ ) -> Type[SubscriberTransport]:
+ """Returns an appropriate transport class.
+
+ Args:
+ label: The name of the desired transport. If none is
+ provided, then the first transport in the registry is used.
+
+ Returns:
+ The transport class to use.
+ """
+ # If a specific transport is requested, return that one.
+ if label:
+ return cls._transport_registry[label]
+
+ # No transport is requested; return the default (that is, the first one
+ # in the dictionary).
+ return next(iter(cls._transport_registry.values()))
+
+
+class SubscriberClient(metaclass=SubscriberClientMeta):
+ """The service that an application uses to manipulate subscriptions and
+ to consume messages from a subscription via the ``Pull`` method or
+ by establishing a bi-directional stream using the ``StreamingPull``
+ method.
+ """
+
+ @staticmethod
+ def _get_default_mtls_endpoint(api_endpoint):
+ """Converts api endpoint to mTLS endpoint.
+
+ Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
+ "*.mtls.sandbox.googleapis.com" and "*.mtls.googleapis.com" respectively.
+ Args:
+ api_endpoint (Optional[str]): the api endpoint to convert.
+ Returns:
+ str: converted mTLS api endpoint.
+ """
+ if not api_endpoint:
+ return api_endpoint
+
+ mtls_endpoint_re = re.compile(
+ r"(?P[^.]+)(?P\.mtls)?(?P\.sandbox)?(?P\.googleapis\.com)?"
+ )
+
+ m = mtls_endpoint_re.match(api_endpoint)
+ name, mtls, sandbox, googledomain = m.groups()
+ if mtls or not googledomain:
+ return api_endpoint
+
+ if sandbox:
+ return api_endpoint.replace(
+ "sandbox.googleapis.com", "mtls.sandbox.googleapis.com"
+ )
+
+ return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
+
+ # The scopes needed to make gRPC calls to all of the methods defined in
+ # this service
+ _DEFAULT_SCOPES = (
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/pubsub",
+ )
+
+ SERVICE_ADDRESS = "pubsub.googleapis.com:443"
+ """The default address of the service."""
+
+ DEFAULT_ENDPOINT = "pubsub.googleapis.com"
+ DEFAULT_MTLS_ENDPOINT = _get_default_mtls_endpoint.__func__( # type: ignore
+ DEFAULT_ENDPOINT
+ )
+
+ @classmethod
+ def from_service_account_info(cls, info: dict, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ info.
+
+ Args:
+ info (dict): The service account private key info.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SubscriberClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_info(info)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ @classmethod
+ def from_service_account_file(cls, filename: str, *args, **kwargs):
+ """Creates an instance of this client using the provided credentials
+ file.
+
+ Args:
+ filename (str): The path to the service account private key json
+ file.
+ args: Additional arguments to pass to the constructor.
+ kwargs: Additional arguments to pass to the constructor.
+
+ Returns:
+ SubscriberClient: The constructed client.
+ """
+ credentials = service_account.Credentials.from_service_account_file(filename)
+ kwargs["credentials"] = credentials
+ return cls(*args, **kwargs)
+
+ from_service_account_json = from_service_account_file
+
+ @property
+ def transport(self) -> SubscriberTransport:
+ """Returns the transport used by the client instance.
+
+ Returns:
+ SubscriberTransport: The transport used by the client
+ instance.
+ """
+ return self._transport
+
+ @staticmethod
+ def snapshot_path(
+ project: str,
+ snapshot: str,
+ ) -> str:
+ """Returns a fully-qualified snapshot string."""
+ return "projects/{project}/snapshots/{snapshot}".format(
+ project=project,
+ snapshot=snapshot,
+ )
+
+ @staticmethod
+ def parse_snapshot_path(path: str) -> Dict[str, str]:
+ """Parses a snapshot path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/snapshots/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def subscription_path(
+ project: str,
+ subscription: str,
+ ) -> str:
+ """Returns a fully-qualified subscription string."""
+ return "projects/{project}/subscriptions/{subscription}".format(
+ project=project,
+ subscription=subscription,
+ )
+
+ @staticmethod
+ def parse_subscription_path(path: str) -> Dict[str, str]:
+ """Parses a subscription path into its component segments."""
+ m = re.match(
+ r"^projects/(?P.+?)/subscriptions/(?P.+?)$", path
+ )
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def topic_path(
+ project: str,
+ topic: str,
+ ) -> str:
+ """Returns a fully-qualified topic string."""
+ return "projects/{project}/topics/{topic}".format(
+ project=project,
+ topic=topic,
+ )
+
+ @staticmethod
+ def parse_topic_path(path: str) -> Dict[str, str]:
+ """Parses a topic path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/topics/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_billing_account_path(
+ billing_account: str,
+ ) -> str:
+ """Returns a fully-qualified billing_account string."""
+ return "billingAccounts/{billing_account}".format(
+ billing_account=billing_account,
+ )
+
+ @staticmethod
+ def parse_common_billing_account_path(path: str) -> Dict[str, str]:
+ """Parse a billing_account path into its component segments."""
+ m = re.match(r"^billingAccounts/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_folder_path(
+ folder: str,
+ ) -> str:
+ """Returns a fully-qualified folder string."""
+ return "folders/{folder}".format(
+ folder=folder,
+ )
+
+ @staticmethod
+ def parse_common_folder_path(path: str) -> Dict[str, str]:
+ """Parse a folder path into its component segments."""
+ m = re.match(r"^folders/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_organization_path(
+ organization: str,
+ ) -> str:
+ """Returns a fully-qualified organization string."""
+ return "organizations/{organization}".format(
+ organization=organization,
+ )
+
+ @staticmethod
+ def parse_common_organization_path(path: str) -> Dict[str, str]:
+ """Parse a organization path into its component segments."""
+ m = re.match(r"^organizations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_project_path(
+ project: str,
+ ) -> str:
+ """Returns a fully-qualified project string."""
+ return "projects/{project}".format(
+ project=project,
+ )
+
+ @staticmethod
+ def parse_common_project_path(path: str) -> Dict[str, str]:
+ """Parse a project path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @staticmethod
+ def common_location_path(
+ project: str,
+ location: str,
+ ) -> str:
+ """Returns a fully-qualified location string."""
+ return "projects/{project}/locations/{location}".format(
+ project=project,
+ location=location,
+ )
+
+ @staticmethod
+ def parse_common_location_path(path: str) -> Dict[str, str]:
+ """Parse a location path into its component segments."""
+ m = re.match(r"^projects/(?P.+?)/locations/(?P.+?)$", path)
+ return m.groupdict() if m else {}
+
+ @classmethod
+ def get_mtls_endpoint_and_cert_source(
+ cls, client_options: Optional[client_options_lib.ClientOptions] = None
+ ):
+ """Return the API endpoint and client cert source for mutual TLS.
+
+ The client cert source is determined in the following order:
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true", the
+ client cert source is None.
+ (2) if `client_options.client_cert_source` is provided, use the provided one; if the
+ default client cert source exists, use the default one; otherwise the client cert
+ source is None.
+
+ The API endpoint is determined in the following order:
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use the
+ default mTLS endpoint; if the environment variabel is "never", use the default API
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint, otherwise
+ use the default API endpoint.
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ Args:
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. Only the `api_endpoint` and `client_cert_source` properties may be used
+ in this method.
+
+ Returns:
+ Tuple[str, Callable[[], Tuple[bytes, bytes]]]: returns the API endpoint and the
+ client cert source to use.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If any errors happen.
+ """
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+ use_client_cert = os.getenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
+ use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto")
+ if use_client_cert not in ("true", "false"):
+ raise ValueError(
+ "Environment variable `GOOGLE_API_USE_CLIENT_CERTIFICATE` must be either `true` or `false`"
+ )
+ if use_mtls_endpoint not in ("auto", "never", "always"):
+ raise MutualTLSChannelError(
+ "Environment variable `GOOGLE_API_USE_MTLS_ENDPOINT` must be `never`, `auto` or `always`"
+ )
+
+ # Figure out the client cert source to use.
+ client_cert_source = None
+ if use_client_cert == "true":
+ if client_options.client_cert_source:
+ client_cert_source = client_options.client_cert_source
+ elif mtls.has_default_client_cert_source():
+ client_cert_source = mtls.default_client_cert_source()
+
+ # Figure out which api endpoint to use.
+ if client_options.api_endpoint is not None:
+ api_endpoint = client_options.api_endpoint
+ elif use_mtls_endpoint == "always" or (
+ use_mtls_endpoint == "auto" and client_cert_source
+ ):
+ api_endpoint = cls.DEFAULT_MTLS_ENDPOINT
+ else:
+ api_endpoint = cls.DEFAULT_ENDPOINT
+
+ return api_endpoint, client_cert_source
+
+ def __init__(
+ self,
+ *,
+ credentials: Optional[ga_credentials.Credentials] = None,
+ transport: Union[str, SubscriberTransport, None] = None,
+ client_options: Optional[client_options_lib.ClientOptions] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ ) -> None:
+ """Instantiates the subscriber client.
+
+ Args:
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ transport (Union[str, SubscriberTransport]): The
+ transport to use. If set to None, a transport is chosen
+ automatically.
+ client_options (google.api_core.client_options.ClientOptions): Custom options for the
+ client. It won't take effect if a ``transport`` instance is provided.
+ (1) The ``api_endpoint`` property can be used to override the
+ default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint:
+ "always" (always use the default mTLS endpoint), "never" (always
+ use the default regular endpoint) and "auto" (auto switch to the
+ default mTLS endpoint if client certificate is present, this is
+ the default value). However, the ``api_endpoint`` property takes
+ precedence if provided.
+ (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE environment variable
+ is "true", then the ``client_cert_source`` property can be used
+ to provide client certificate for mutual TLS transport. If
+ not provided, the default SSL client certificate will be used if
+ present. If GOOGLE_API_USE_CLIENT_CERTIFICATE is "false" or not
+ set, no client certificate will be used.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ """
+ if isinstance(client_options, dict):
+ client_options = client_options_lib.from_dict(client_options)
+ if client_options is None:
+ client_options = client_options_lib.ClientOptions()
+
+ api_endpoint, client_cert_source_func = self.get_mtls_endpoint_and_cert_source(
+ client_options
+ )
+
+ api_key_value = getattr(client_options, "api_key", None)
+ if api_key_value and credentials:
+ raise ValueError(
+ "client_options.api_key and credentials are mutually exclusive"
+ )
+
+ # Save or instantiate the transport.
+ # Ordinarily, we provide the transport, but allowing a custom transport
+ # instance provides an extensibility point for unusual situations.
+ if isinstance(transport, SubscriberTransport):
+ # transport is a SubscriberTransport instance.
+ if credentials or client_options.credentials_file or api_key_value:
+ raise ValueError(
+ "When providing a transport instance, "
+ "provide its credentials directly."
+ )
+ if client_options.scopes:
+ raise ValueError(
+ "When providing a transport instance, provide its scopes "
+ "directly."
+ )
+ self._transport = transport
+ else:
+ import google.auth._default # type: ignore
+
+ if api_key_value and hasattr(
+ google.auth._default, "get_api_key_credentials"
+ ):
+ credentials = google.auth._default.get_api_key_credentials(
+ api_key_value
+ )
+
+ Transport = type(self).get_transport_class(transport)
+
+ emulator_host = os.environ.get("PUBSUB_EMULATOR_HOST")
+ if emulator_host:
+ if issubclass(Transport, type(self)._transport_registry["grpc"]):
+ channel = grpc.insecure_channel(target=emulator_host)
+ else:
+ channel = grpc.aio.insecure_channel(target=emulator_host)
+ Transport = functools.partial(Transport, channel=channel)
+
+ self._transport = Transport(
+ credentials=credentials,
+ credentials_file=client_options.credentials_file,
+ host=api_endpoint,
+ scopes=client_options.scopes,
+ client_cert_source_for_mtls=client_cert_source_func,
+ quota_project_id=client_options.quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=True,
+ api_audience=client_options.api_audience,
+ )
+
+ def create_subscription(
+ self,
+ request: Union[pubsub.Subscription, dict] = None,
+ *,
+ name: str = None,
+ topic: str = None,
+ push_config: pubsub.PushConfig = None,
+ ack_deadline_seconds: int = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Subscription:
+ r"""Creates a subscription to a given topic. See the [resource name
+ rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). If
+ the subscription already exists, returns ``ALREADY_EXISTS``. If
+ the corresponding topic doesn't exist, returns ``NOT_FOUND``.
+
+ If the name is not provided in the request, the server will
+ assign a random name for this subscription on the same project
+ as the topic, conforming to the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Subscription object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_create_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.Subscription(
+ name="name_value",
+ topic="topic_value",
+ )
+
+ # Make the request
+ response = client.create_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.Subscription, dict]):
+ The request object. A subscription resource.
+ name (str):
+ Required. The name of the subscription. It must have the
+ format
+ ``"projects/{project}/subscriptions/{subscription}"``.
+ ``{subscription}`` must start with a letter, and contain
+ only letters (``[A-Za-z]``), numbers (``[0-9]``), dashes
+ (``-``), underscores (``_``), periods (``.``), tildes
+ (``~``), plus (``+``) or percent signs (``%``). It must
+ be between 3 and 255 characters in length, and it must
+ not start with ``"goog"``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ topic (str):
+ Required. The name of the topic from which this
+ subscription is receiving messages. Format is
+ ``projects/{project}/topics/{topic}``. The value of this
+ field will be ``_deleted-topic_`` if the topic has been
+ deleted.
+
+ This corresponds to the ``topic`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ push_config (google.pubsub_v1.types.PushConfig):
+ If push delivery is used with this subscription, this
+ field is used to configure it. Either ``pushConfig`` or
+ ``bigQueryConfig`` can be set, but not both. If both are
+ empty, then the subscriber will pull and ack messages
+ using API methods.
+
+ This corresponds to the ``push_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_deadline_seconds (int):
+ The approximate amount of time (on a best-effort basis)
+ Pub/Sub waits for the subscriber to acknowledge receipt
+ before resending the message. In the interval after the
+ message is delivered and before it is acknowledged, it
+ is considered to be outstanding. During that time
+ period, the message will not be redelivered (on a
+ best-effort basis).
+
+ For pull subscriptions, this value is used as the
+ initial value for the ack deadline. To override this
+ value for a given message, call ``ModifyAckDeadline``
+ with the corresponding ``ack_id`` if using non-streaming
+ pull or send the ``ack_id`` in a
+ ``StreamingModifyAckDeadlineRequest`` if using streaming
+ pull. The minimum custom deadline you can specify is 10
+ seconds. The maximum custom deadline you can specify is
+ 600 seconds (10 minutes). If this parameter is 0, a
+ default value of 10 seconds is used.
+
+ For push delivery, this value is also used to set the
+ request timeout for the call to the push endpoint.
+
+ If the subscriber never acknowledges the message, the
+ Pub/Sub system will eventually redeliver the message.
+
+ This corresponds to the ``ack_deadline_seconds`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Subscription:
+ A subscription resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name, topic, push_config, ack_deadline_seconds])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.Subscription.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.Subscription):
+ request = pubsub.Subscription(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+ if topic is not None:
+ request.topic = topic
+ if push_config is not None:
+ request.push_config = push_config
+ if ack_deadline_seconds is not None:
+ request.ack_deadline_seconds = ack_deadline_seconds
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.create_subscription]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def get_subscription(
+ self,
+ request: Union[pubsub.GetSubscriptionRequest, dict] = None,
+ *,
+ subscription: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Subscription:
+ r"""Gets the configuration details of a subscription.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_get_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetSubscriptionRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = client.get_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetSubscriptionRequest, dict]):
+ The request object. Request for the GetSubscription
+ method.
+ subscription (str):
+ Required. The name of the subscription to get. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Subscription:
+ A subscription resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.GetSubscriptionRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.GetSubscriptionRequest):
+ request = pubsub.GetSubscriptionRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.get_subscription]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def update_subscription(
+ self,
+ request: Union[pubsub.UpdateSubscriptionRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Subscription:
+ r"""Updates an existing subscription. Note that certain
+ properties of a subscription, such as its topic, are not
+ modifiable.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_update_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ subscription = pubsub_v1.Subscription()
+ subscription.name = "name_value"
+ subscription.topic = "topic_value"
+
+ request = pubsub_v1.UpdateSubscriptionRequest(
+ subscription=subscription,
+ )
+
+ # Make the request
+ response = client.update_subscription(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.UpdateSubscriptionRequest, dict]):
+ The request object. Request for the UpdateSubscription
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Subscription:
+ A subscription resource.
+ """
+ # Create or coerce a protobuf request object.
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.UpdateSubscriptionRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.UpdateSubscriptionRequest):
+ request = pubsub.UpdateSubscriptionRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.update_subscription]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription.name", request.subscription.name),)
+ ),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def list_subscriptions(
+ self,
+ request: Union[pubsub.ListSubscriptionsRequest, dict] = None,
+ *,
+ project: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListSubscriptionsPager:
+ r"""Lists matching subscriptions.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_list_subscriptions():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListSubscriptionsRequest(
+ project="project_value",
+ )
+
+ # Make the request
+ page_result = client.list_subscriptions(request=request)
+
+ # Handle the response
+ for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListSubscriptionsRequest, dict]):
+ The request object. Request for the `ListSubscriptions`
+ method.
+ project (str):
+ Required. The name of the project in which to list
+ subscriptions. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``project`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager:
+ Response for the ListSubscriptions method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([project])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.ListSubscriptionsRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.ListSubscriptionsRequest):
+ request = pubsub.ListSubscriptionsRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if project is not None:
+ request.project = project
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_subscriptions]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__iter__` convenience method.
+ response = pagers.ListSubscriptionsPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def delete_subscription(
+ self,
+ request: Union[pubsub.DeleteSubscriptionRequest, dict] = None,
+ *,
+ subscription: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Deletes an existing subscription. All messages retained in the
+ subscription are immediately dropped. Calls to ``Pull`` after
+ deletion will return ``NOT_FOUND``. After a subscription is
+ deleted, a new one may be created with the same name, but the
+ new one has no association with the old subscription or its
+ topic unless the same topic is specified.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_delete_subscription():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteSubscriptionRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ client.delete_subscription(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteSubscriptionRequest, dict]):
+ The request object. Request for the DeleteSubscription
+ method.
+ subscription (str):
+ Required. The subscription to delete. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.DeleteSubscriptionRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.DeleteSubscriptionRequest):
+ request = pubsub.DeleteSubscriptionRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.delete_subscription]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ def modify_ack_deadline(
+ self,
+ request: Union[pubsub.ModifyAckDeadlineRequest, dict] = None,
+ *,
+ subscription: str = None,
+ ack_ids: Sequence[str] = None,
+ ack_deadline_seconds: int = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Modifies the ack deadline for a specific message. This method is
+ useful to indicate that more time is needed to process a message
+ by the subscriber, or to make the message available for
+ redelivery if the processing was interrupted. Note that this
+ does not modify the subscription-level ``ackDeadlineSeconds``
+ used for subsequent messages.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_modify_ack_deadline():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ModifyAckDeadlineRequest(
+ subscription="subscription_value",
+ ack_ids=['ack_ids_value1', 'ack_ids_value2'],
+ ack_deadline_seconds=2066,
+ )
+
+ # Make the request
+ client.modify_ack_deadline(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ModifyAckDeadlineRequest, dict]):
+ The request object. Request for the ModifyAckDeadline
+ method.
+ subscription (str):
+ Required. The name of the subscription. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_ids (Sequence[str]):
+ Required. List of acknowledgment IDs.
+ This corresponds to the ``ack_ids`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_deadline_seconds (int):
+ Required. The new ack deadline with respect to the time
+ this request was sent to the Pub/Sub system. For
+ example, if the value is 10, the new ack deadline will
+ expire 10 seconds after the ``ModifyAckDeadline`` call
+ was made. Specifying zero might immediately make the
+ message available for delivery to another subscriber
+ client. This typically results in an increase in the
+ rate of message redeliveries (that is, duplicates). The
+ minimum deadline you can specify is 0 seconds. The
+ maximum deadline you can specify is 600 seconds (10
+ minutes).
+
+ This corresponds to the ``ack_deadline_seconds`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, ack_ids, ack_deadline_seconds])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.ModifyAckDeadlineRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.ModifyAckDeadlineRequest):
+ request = pubsub.ModifyAckDeadlineRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if ack_ids is not None:
+ request.ack_ids = ack_ids
+ if ack_deadline_seconds is not None:
+ request.ack_deadline_seconds = ack_deadline_seconds
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.modify_ack_deadline]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ def acknowledge(
+ self,
+ request: Union[pubsub.AcknowledgeRequest, dict] = None,
+ *,
+ subscription: str = None,
+ ack_ids: Sequence[str] = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Acknowledges the messages associated with the ``ack_ids`` in the
+ ``AcknowledgeRequest``. The Pub/Sub system can remove the
+ relevant messages from the subscription.
+
+ Acknowledging a message whose ack deadline has expired may
+ succeed, but such a message may be redelivered later.
+ Acknowledging a message more than once will not result in an
+ error.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_acknowledge():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.AcknowledgeRequest(
+ subscription="subscription_value",
+ ack_ids=['ack_ids_value1', 'ack_ids_value2'],
+ )
+
+ # Make the request
+ client.acknowledge(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.AcknowledgeRequest, dict]):
+ The request object. Request for the Acknowledge method.
+ subscription (str):
+ Required. The subscription whose message is being
+ acknowledged. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ ack_ids (Sequence[str]):
+ Required. The acknowledgment ID for the messages being
+ acknowledged that was returned by the Pub/Sub system in
+ the ``Pull`` response. Must not be empty.
+
+ This corresponds to the ``ack_ids`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, ack_ids])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.AcknowledgeRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.AcknowledgeRequest):
+ request = pubsub.AcknowledgeRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if ack_ids is not None:
+ request.ack_ids = ack_ids
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.acknowledge]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ def pull(
+ self,
+ request: Union[pubsub.PullRequest, dict] = None,
+ *,
+ subscription: str = None,
+ return_immediately: bool = None,
+ max_messages: int = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.PullResponse:
+ r"""Pulls messages from the server. The server may return
+ ``UNAVAILABLE`` if there are too many concurrent pull requests
+ pending for the given subscription.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_pull():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.PullRequest(
+ subscription="subscription_value",
+ max_messages=1277,
+ )
+
+ # Make the request
+ response = client.pull(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.PullRequest, dict]):
+ The request object. Request for the `Pull` method.
+ subscription (str):
+ Required. The subscription from which messages should be
+ pulled. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ return_immediately (bool):
+ Optional. If this field set to true, the system will
+ respond immediately even if it there are no messages
+ available to return in the ``Pull`` response. Otherwise,
+ the system may wait (for a bounded amount of time) until
+ at least one message is available, rather than returning
+ no messages. Warning: setting this field to ``true`` is
+ discouraged because it adversely impacts the performance
+ of ``Pull`` operations. We recommend that users do not
+ set this field.
+
+ This corresponds to the ``return_immediately`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ max_messages (int):
+ Required. The maximum number of
+ messages to return for this request.
+ Must be a positive integer. The Pub/Sub
+ system may return fewer than the number
+ specified.
+
+ This corresponds to the ``max_messages`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.PullResponse:
+ Response for the Pull method.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, return_immediately, max_messages])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.PullRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.PullRequest):
+ request = pubsub.PullRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if return_immediately is not None:
+ request.return_immediately = return_immediately
+ if max_messages is not None:
+ request.max_messages = max_messages
+
+ if request.return_immediately:
+ warnings.warn(
+ "The return_immediately flag is deprecated and should be set to False.",
+ category=DeprecationWarning,
+ )
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.pull]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def streaming_pull(
+ self,
+ requests: Iterator[pubsub.StreamingPullRequest] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> Iterable[pubsub.StreamingPullResponse]:
+ r"""Establishes a stream with the server, which sends messages down
+ to the client. The client streams acknowledgements and ack
+ deadline modifications back to the server. The server will close
+ the stream and return the status on any error. The server may
+ close the stream with status ``UNAVAILABLE`` to reassign
+ server-side resources, in which case, the client should
+ re-establish the stream. Flow control can be achieved by
+ configuring the underlying RPC channel.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_streaming_pull():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.StreamingPullRequest(
+ subscription="subscription_value",
+ stream_ack_deadline_seconds=2813,
+ )
+
+ # This method expects an iterator which contains
+ # 'pubsub_v1.StreamingPullRequest' objects
+ # Here we create a generator that yields a single `request` for
+ # demonstrative purposes.
+ requests = [request]
+
+ def request_generator():
+ for request in requests:
+ yield request
+
+ # Make the request
+ stream = client.streaming_pull(requests=request_generator())
+
+ # Handle the response
+ for response in stream:
+ print(response)
+
+ Args:
+ requests (Iterator[google.pubsub_v1.types.StreamingPullRequest]):
+ The request object iterator. Request for the `StreamingPull`
+ streaming RPC method. This request is used to establish
+ the initial stream as well as to stream acknowledgements
+ and ack deadline modifications from the client to the
+ server.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ Iterable[google.pubsub_v1.types.StreamingPullResponse]:
+ Response for the StreamingPull method. This response is used to stream
+ messages from the server to the client.
+
+ """
+
+ # Wrappers in api-core should not automatically pre-fetch the first
+ # stream result, as this breaks the stream when re-opening it.
+ # https://github.com/googleapis/python-pubsub/issues/93#issuecomment-630762257
+ self._transport.streaming_pull._prefetch_first_result_ = False
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.streaming_pull]
+
+ # Send the request.
+ response = rpc(
+ requests,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def modify_push_config(
+ self,
+ request: Union[pubsub.ModifyPushConfigRequest, dict] = None,
+ *,
+ subscription: str = None,
+ push_config: pubsub.PushConfig = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Modifies the ``PushConfig`` for a specified subscription.
+
+ This may be used to change a push subscription to a pull one
+ (signified by an empty ``PushConfig``) or vice versa, or change
+ the endpoint URL and other attributes of a push subscription.
+ Messages will accumulate for delivery continuously through the
+ call regardless of changes to the ``PushConfig``.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_modify_push_config():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ModifyPushConfigRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ client.modify_push_config(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ModifyPushConfigRequest, dict]):
+ The request object. Request for the ModifyPushConfig
+ method.
+ subscription (str):
+ Required. The name of the subscription. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ push_config (google.pubsub_v1.types.PushConfig):
+ Required. The push configuration for future deliveries.
+
+ An empty ``pushConfig`` indicates that the Pub/Sub
+ system should stop pushing messages from the given
+ subscription and allow messages to be pulled and
+ acknowledged - effectively pausing the subscription if
+ ``Pull`` or ``StreamingPull`` is not called.
+
+ This corresponds to the ``push_config`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([subscription, push_config])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.ModifyPushConfigRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.ModifyPushConfigRequest):
+ request = pubsub.ModifyPushConfigRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if subscription is not None:
+ request.subscription = subscription
+ if push_config is not None:
+ request.push_config = push_config
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.modify_push_config]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ def get_snapshot(
+ self,
+ request: Union[pubsub.GetSnapshotRequest, dict] = None,
+ *,
+ snapshot: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Snapshot:
+ r"""Gets the configuration details of a snapshot.
+ Snapshots are used in Seek
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_get_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.GetSnapshotRequest(
+ snapshot="snapshot_value",
+ )
+
+ # Make the request
+ response = client.get_snapshot(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.GetSnapshotRequest, dict]):
+ The request object. Request for the GetSnapshot method.
+ snapshot (str):
+ Required. The name of the snapshot to get. Format is
+ ``projects/{project}/snapshots/{snap}``.
+
+ This corresponds to the ``snapshot`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Snapshot:
+ A snapshot resource. Snapshots are used in
+ [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([snapshot])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.GetSnapshotRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.GetSnapshotRequest):
+ request = pubsub.GetSnapshotRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if snapshot is not None:
+ request.snapshot = snapshot
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.get_snapshot]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("snapshot", request.snapshot),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def list_snapshots(
+ self,
+ request: Union[pubsub.ListSnapshotsRequest, dict] = None,
+ *,
+ project: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListSnapshotsPager:
+ r"""Lists the existing snapshots. Snapshots are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_list_snapshots():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.ListSnapshotsRequest(
+ project="project_value",
+ )
+
+ # Make the request
+ page_result = client.list_snapshots(request=request)
+
+ # Handle the response
+ for response in page_result:
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.ListSnapshotsRequest, dict]):
+ The request object. Request for the `ListSnapshots`
+ method.
+ project (str):
+ Required. The name of the project in which to list
+ snapshots. Format is ``projects/{project-id}``.
+
+ This corresponds to the ``project`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager:
+ Response for the ListSnapshots method.
+
+ Iterating over this object will yield results and
+ resolve additional pages automatically.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([project])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.ListSnapshotsRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.ListSnapshotsRequest):
+ request = pubsub.ListSnapshotsRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if project is not None:
+ request.project = project
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.list_snapshots]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("project", request.project),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # This method is paged; wrap the response in a pager, which provides
+ # an `__iter__` convenience method.
+ response = pagers.ListSnapshotsPager(
+ method=rpc,
+ request=request,
+ response=response,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def create_snapshot(
+ self,
+ request: Union[pubsub.CreateSnapshotRequest, dict] = None,
+ *,
+ name: str = None,
+ subscription: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Snapshot:
+ r"""Creates a snapshot from the requested subscription. Snapshots
+ are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ If the snapshot already exists, returns ``ALREADY_EXISTS``. If
+ the requested subscription doesn't exist, returns ``NOT_FOUND``.
+ If the backlog in the subscription is too old -- and the
+ resulting snapshot would expire in less than 1 hour -- then
+ ``FAILED_PRECONDITION`` is returned. See also the
+ ``Snapshot.expire_time`` field. If the name is not provided in
+ the request, the server will assign a random name for this
+ snapshot on the same project as the subscription, conforming to
+ the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Snapshot object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_create_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.CreateSnapshotRequest(
+ name="name_value",
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = client.create_snapshot(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.CreateSnapshotRequest, dict]):
+ The request object. Request for the `CreateSnapshot`
+ method.
+ name (str):
+ Required. User-provided name for this snapshot. If the
+ name is not provided in the request, the server will
+ assign a random name for this snapshot on the same
+ project as the subscription. Note that for REST API
+ requests, you must specify a name. See the resource name
+ rules. Format is
+ ``projects/{project}/snapshots/{snap}``.
+
+ This corresponds to the ``name`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ subscription (str):
+ Required. The subscription whose backlog the snapshot
+ retains. Specifically, the created snapshot is
+ guaranteed to retain: (a) The existing backlog on the
+ subscription. More precisely, this is defined as the
+ messages in the subscription's backlog that are
+ unacknowledged upon the successful completion of the
+ ``CreateSnapshot`` request; as well as: (b) Any messages
+ published to the subscription's topic following the
+ successful completion of the CreateSnapshot request.
+ Format is ``projects/{project}/subscriptions/{sub}``.
+
+ This corresponds to the ``subscription`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Snapshot:
+ A snapshot resource. Snapshots are used in
+ [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([name, subscription])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.CreateSnapshotRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.CreateSnapshotRequest):
+ request = pubsub.CreateSnapshotRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if name is not None:
+ request.name = name
+ if subscription is not None:
+ request.subscription = subscription
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.create_snapshot]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("name", request.name),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def update_snapshot(
+ self,
+ request: Union[pubsub.UpdateSnapshotRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.Snapshot:
+ r"""Updates an existing snapshot. Snapshots are used in
+ Seek
+ operations, which allow
+ you to manage message acknowledgments in bulk. That is,
+ you can set the acknowledgment state of messages in an
+ existing subscription to the state captured by a
+ snapshot.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_update_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.UpdateSnapshotRequest(
+ )
+
+ # Make the request
+ response = client.update_snapshot(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.UpdateSnapshotRequest, dict]):
+ The request object. Request for the UpdateSnapshot
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.Snapshot:
+ A snapshot resource. Snapshots are used in
+ [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ """
+ # Create or coerce a protobuf request object.
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.UpdateSnapshotRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.UpdateSnapshotRequest):
+ request = pubsub.UpdateSnapshotRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.update_snapshot]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("snapshot.name", request.snapshot.name),)
+ ),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def delete_snapshot(
+ self,
+ request: Union[pubsub.DeleteSnapshotRequest, dict] = None,
+ *,
+ snapshot: str = None,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> None:
+ r"""Removes an existing snapshot. Snapshots are used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ When the snapshot is deleted, all messages retained in the
+ snapshot are immediately dropped. After a snapshot is deleted, a
+ new one may be created with the same name, but the new one has
+ no association with the old snapshot or its subscription, unless
+ the same subscription is specified.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_delete_snapshot():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.DeleteSnapshotRequest(
+ snapshot="snapshot_value",
+ )
+
+ # Make the request
+ client.delete_snapshot(request=request)
+
+ Args:
+ request (Union[google.pubsub_v1.types.DeleteSnapshotRequest, dict]):
+ The request object. Request for the `DeleteSnapshot`
+ method.
+ snapshot (str):
+ Required. The name of the snapshot to delete. Format is
+ ``projects/{project}/snapshots/{snap}``.
+
+ This corresponds to the ``snapshot`` field
+ on the ``request`` instance; if ``request`` is provided, this
+ should not be set.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ # Create or coerce a protobuf request object.
+ # Quick check: If we got a request object, we should *not* have
+ # gotten any keyword arguments that map to the request.
+ has_flattened_params = any([snapshot])
+ if request is not None and has_flattened_params:
+ raise ValueError(
+ "If the `request` argument is set, then none of "
+ "the individual field arguments should be set."
+ )
+
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.DeleteSnapshotRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.DeleteSnapshotRequest):
+ request = pubsub.DeleteSnapshotRequest(request)
+ # If we have keyword arguments corresponding to fields on the
+ # request, apply these.
+ if snapshot is not None:
+ request.snapshot = snapshot
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.delete_snapshot]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("snapshot", request.snapshot),)),
+ )
+
+ # Send the request.
+ rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ def seek(
+ self,
+ request: Union[pubsub.SeekRequest, dict] = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pubsub.SeekResponse:
+ r"""Seeks an existing subscription to a point in time or to a given
+ snapshot, whichever is provided in the request. Snapshots are
+ used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ Note that both the subscription and the snapshot must be on the
+ same topic.
+
+ .. code-block:: python
+
+ # This snippet has been automatically generated and should be regarded as a
+ # code template only.
+ # It will require modifications to work:
+ # - It may require correct/in-range values for request initialization.
+ # - It may require specifying regional endpoints when creating the service
+ # client as shown in:
+ # https://googleapis.dev/python/google-api-core/latest/client_options.html
+ from google import pubsub_v1
+
+ def sample_seek():
+ # Create a client
+ client = pubsub_v1.SubscriberClient()
+
+ # Initialize request argument(s)
+ request = pubsub_v1.SeekRequest(
+ subscription="subscription_value",
+ )
+
+ # Make the request
+ response = client.seek(request=request)
+
+ # Handle the response
+ print(response)
+
+ Args:
+ request (Union[google.pubsub_v1.types.SeekRequest, dict]):
+ The request object. Request for the `Seek` method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+
+ Returns:
+ google.pubsub_v1.types.SeekResponse:
+ Response for the Seek method (this response is empty).
+ """
+ # Create or coerce a protobuf request object.
+ # Minor optimization to avoid making a copy if the user passes
+ # in a pubsub.SeekRequest.
+ # There's no risk of modifying the input as we've already verified
+ # there are no flattened fields.
+ if not isinstance(request, pubsub.SeekRequest):
+ request = pubsub.SeekRequest(request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = self._transport._wrapped_methods[self._transport.seek]
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata(
+ (("subscription", request.subscription),)
+ ),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, type, value, traceback):
+ """Releases underlying transport's resources.
+
+ .. warning::
+ ONLY use as a context manager if the transport is NOT shared
+ with other clients! Exiting the with block will CLOSE the transport
+ and may cause errors in other clients!
+ """
+ self.transport.close()
+
+ def set_iam_policy(
+ self,
+ request: iam_policy_pb2.SetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Sets the IAM access control policy on the specified function.
+
+ Replaces any existing policy.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.SetIamPolicyRequest`):
+ The request object. Request message for `SetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if any,
+ should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.SetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.set_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def get_iam_policy(
+ self,
+ request: iam_policy_pb2.GetIamPolicyRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> policy_pb2.Policy:
+ r"""Gets the IAM access control policy for a function.
+
+ Returns an empty policy if the function exists and does not have a
+ policy set.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.GetIamPolicyRequest`):
+ The request object. Request message for `GetIamPolicy`
+ method.
+ retry (google.api_core.retry.Retry): Designation of what errors, if
+ any, should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.policy_pb2.Policy:
+ Defines an Identity and Access Management (IAM) policy.
+ It is used to specify access control policies for Cloud
+ Platform resources.
+ A ``Policy`` is a collection of ``bindings``. A
+ ``binding`` binds one or more ``members`` to a single
+ ``role``. Members can be user accounts, service
+ accounts, Google groups, and domains (such as G Suite).
+ A ``role`` is a named list of permissions (defined by
+ IAM or configured by users). A ``binding`` can
+ optionally specify a ``condition``, which is a logic
+ expression that further constrains the role binding
+ based on attributes about the request and/or target
+ resource.
+
+ **JSON Example**
+
+ ::
+
+ {
+ "bindings": [
+ {
+ "role": "roles/resourcemanager.organizationAdmin",
+ "members": [
+ "user:mike@example.com",
+ "group:admins@example.com",
+ "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com"
+ ]
+ },
+ {
+ "role": "roles/resourcemanager.organizationViewer",
+ "members": ["user:eve@example.com"],
+ "condition": {
+ "title": "expirable access",
+ "description": "Does not grant access after Sep 2020",
+ "expression": "request.time <
+ timestamp('2020-10-01T00:00:00.000Z')",
+ }
+ }
+ ]
+ }
+
+ **YAML Example**
+
+ ::
+
+ bindings:
+ - members:
+ - user:mike@example.com
+ - group:admins@example.com
+ - domain:google.com
+ - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin
+ - members:
+ - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer
+ condition:
+ title: expirable access
+ description: Does not grant access after Sep 2020
+ expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
+
+ For a description of IAM and its features, see the `IAM
+ developer's
+ guide `__.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.GetIamPolicyRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.get_iam_policy,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+ def test_iam_permissions(
+ self,
+ request: iam_policy_pb2.TestIamPermissionsRequest = None,
+ *,
+ retry: OptionalRetry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> iam_policy_pb2.TestIamPermissionsResponse:
+ r"""Tests the specified IAM permissions against the IAM access control
+ policy for a function.
+
+ If the function does not exist, this will return an empty set
+ of permissions, not a NOT_FOUND error.
+
+ Args:
+ request (:class:`~.iam_policy_pb2.TestIamPermissionsRequest`):
+ The request object. Request message for
+ `TestIamPermissions` method.
+ retry (google.api_core.retry.Retry): Designation of what errors,
+ if any, should be retried.
+ timeout (float): The timeout for this request.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ Returns:
+ ~.iam_policy_pb2.TestIamPermissionsResponse:
+ Response message for ``TestIamPermissions`` method.
+ """
+ # Create or coerce a protobuf request object.
+
+ # The request isn't a proto-plus wrapped type,
+ # so it must be constructed via keyword expansion.
+ if isinstance(request, dict):
+ request = iam_policy_pb2.TestIamPermissionsRequest(**request)
+
+ # Wrap the RPC method; this adds retry and timeout information,
+ # and friendly error handling.
+ rpc = gapic_v1.method.wrap_method(
+ self._transport.test_iam_permissions,
+ default_timeout=None,
+ client_info=DEFAULT_CLIENT_INFO,
+ )
+
+ # Certain fields should be provided within the metadata header;
+ # add these here.
+ metadata = tuple(metadata) + (
+ gapic_v1.routing_header.to_grpc_metadata((("resource", request.resource),)),
+ )
+
+ # Send the request.
+ response = rpc(
+ request,
+ retry=retry,
+ timeout=timeout,
+ metadata=metadata,
+ )
+
+ # Done; return the response.
+ return response
+
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+__all__ = ("SubscriberClient",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
new file mode 100644
index 000000000000..cb3896bb59fa
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
@@ -0,0 +1,283 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import (
+ Any,
+ AsyncIterator,
+ Awaitable,
+ Callable,
+ Sequence,
+ Tuple,
+ Optional,
+ Iterator,
+)
+
+from google.pubsub_v1.types import pubsub
+
+
+class ListSubscriptionsPager:
+ """A pager for iterating through ``list_subscriptions`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListSubscriptionsResponse` object, and
+ provides an ``__iter__`` method to iterate through its
+ ``subscriptions`` field.
+
+ If there are more pages, the ``__iter__`` method will make additional
+ ``ListSubscriptions`` requests and continue to iterate
+ through the ``subscriptions`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListSubscriptionsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., pubsub.ListSubscriptionsResponse],
+ request: pubsub.ListSubscriptionsRequest,
+ response: pubsub.ListSubscriptionsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiate the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListSubscriptionsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListSubscriptionsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListSubscriptionsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ def pages(self) -> Iterator[pubsub.ListSubscriptionsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __iter__(self) -> Iterator[pubsub.Subscription]:
+ for page in self.pages:
+ yield from page.subscriptions
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListSubscriptionsAsyncPager:
+ """A pager for iterating through ``list_subscriptions`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListSubscriptionsResponse` object, and
+ provides an ``__aiter__`` method to iterate through its
+ ``subscriptions`` field.
+
+ If there are more pages, the ``__aiter__`` method will make additional
+ ``ListSubscriptions`` requests and continue to iterate
+ through the ``subscriptions`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListSubscriptionsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., Awaitable[pubsub.ListSubscriptionsResponse]],
+ request: pubsub.ListSubscriptionsRequest,
+ response: pubsub.ListSubscriptionsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiates the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListSubscriptionsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListSubscriptionsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListSubscriptionsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ async def pages(self) -> AsyncIterator[pubsub.ListSubscriptionsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = await self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __aiter__(self) -> AsyncIterator[pubsub.Subscription]:
+ async def async_generator():
+ async for page in self.pages:
+ for response in page.subscriptions:
+ yield response
+
+ return async_generator()
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListSnapshotsPager:
+ """A pager for iterating through ``list_snapshots`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListSnapshotsResponse` object, and
+ provides an ``__iter__`` method to iterate through its
+ ``snapshots`` field.
+
+ If there are more pages, the ``__iter__`` method will make additional
+ ``ListSnapshots`` requests and continue to iterate
+ through the ``snapshots`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListSnapshotsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., pubsub.ListSnapshotsResponse],
+ request: pubsub.ListSnapshotsRequest,
+ response: pubsub.ListSnapshotsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiate the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListSnapshotsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListSnapshotsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListSnapshotsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ def pages(self) -> Iterator[pubsub.ListSnapshotsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __iter__(self) -> Iterator[pubsub.Snapshot]:
+ for page in self.pages:
+ yield from page.snapshots
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
+
+
+class ListSnapshotsAsyncPager:
+ """A pager for iterating through ``list_snapshots`` requests.
+
+ This class thinly wraps an initial
+ :class:`google.pubsub_v1.types.ListSnapshotsResponse` object, and
+ provides an ``__aiter__`` method to iterate through its
+ ``snapshots`` field.
+
+ If there are more pages, the ``__aiter__`` method will make additional
+ ``ListSnapshots`` requests and continue to iterate
+ through the ``snapshots`` field on the
+ corresponding responses.
+
+ All the usual :class:`google.pubsub_v1.types.ListSnapshotsResponse`
+ attributes are available on the pager. If multiple requests are made, only
+ the most recent response is retained, and thus used for attribute lookup.
+ """
+
+ def __init__(
+ self,
+ method: Callable[..., Awaitable[pubsub.ListSnapshotsResponse]],
+ request: pubsub.ListSnapshotsRequest,
+ response: pubsub.ListSnapshotsResponse,
+ *,
+ metadata: Sequence[Tuple[str, str]] = ()
+ ):
+ """Instantiates the pager.
+
+ Args:
+ method (Callable): The method that was originally called, and
+ which instantiated this pager.
+ request (google.pubsub_v1.types.ListSnapshotsRequest):
+ The initial request object.
+ response (google.pubsub_v1.types.ListSnapshotsResponse):
+ The initial response object.
+ metadata (Sequence[Tuple[str, str]]): Strings which should be
+ sent along with the request as metadata.
+ """
+ self._method = method
+ self._request = pubsub.ListSnapshotsRequest(request)
+ self._response = response
+ self._metadata = metadata
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._response, name)
+
+ @property
+ async def pages(self) -> AsyncIterator[pubsub.ListSnapshotsResponse]:
+ yield self._response
+ while self._response.next_page_token:
+ self._request.page_token = self._response.next_page_token
+ self._response = await self._method(self._request, metadata=self._metadata)
+ yield self._response
+
+ def __aiter__(self) -> AsyncIterator[pubsub.Snapshot]:
+ async def async_generator():
+ async for page in self.pages:
+ for response in page.snapshots:
+ yield response
+
+ return async_generator()
+
+ def __repr__(self) -> str:
+ return "{0}<{1!r}>".format(self.__class__.__name__, self._response)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/__init__.py
new file mode 100644
index 000000000000..f71cdecd4a4c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/__init__.py
@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from collections import OrderedDict
+from typing import Dict, Type
+
+from .base import SubscriberTransport
+from .grpc import SubscriberGrpcTransport
+from .grpc_asyncio import SubscriberGrpcAsyncIOTransport
+
+
+# Compile a registry of transports.
+_transport_registry = OrderedDict() # type: Dict[str, Type[SubscriberTransport]]
+_transport_registry["grpc"] = SubscriberGrpcTransport
+_transport_registry["grpc_asyncio"] = SubscriberGrpcAsyncIOTransport
+
+__all__ = (
+ "SubscriberTransport",
+ "SubscriberGrpcTransport",
+ "SubscriberGrpcAsyncIOTransport",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/base.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/base.py
new file mode 100644
index 000000000000..0d815e06890a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/base.py
@@ -0,0 +1,567 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import abc
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Union
+import pkg_resources
+
+import google.auth # type: ignore
+import google.api_core
+from google.api_core import exceptions as core_exceptions
+from google.api_core import gapic_v1
+from google.api_core import retry as retries
+from google.auth import credentials as ga_credentials # type: ignore
+from google.oauth2 import service_account # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import pubsub
+
+try:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo(
+ client_library_version=pkg_resources.get_distribution(
+ "google-cloud-pubsub",
+ ).version,
+ )
+except pkg_resources.DistributionNotFound:
+ DEFAULT_CLIENT_INFO = gapic_v1.client_info.ClientInfo()
+
+
+class SubscriberTransport(abc.ABC):
+ """Abstract transport class for Subscriber."""
+
+ AUTH_SCOPES = (
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/pubsub",
+ )
+
+ DEFAULT_HOST: str = "pubsub.googleapis.com"
+
+ def __init__(
+ self,
+ *,
+ host: str = DEFAULT_HOST,
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ **kwargs,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A list of scopes.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+ """
+
+ scopes_kwargs = {"scopes": scopes, "default_scopes": self.AUTH_SCOPES}
+
+ # Save the scopes.
+ self._scopes = scopes
+
+ # If no credentials are provided, then determine the appropriate
+ # defaults.
+ if credentials and credentials_file:
+ raise core_exceptions.DuplicateCredentialArgs(
+ "'credentials_file' and 'credentials' are mutually exclusive"
+ )
+
+ if credentials_file is not None:
+ credentials, _ = google.auth.load_credentials_from_file(
+ credentials_file, **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ elif credentials is None:
+ credentials, _ = google.auth.default(
+ **scopes_kwargs, quota_project_id=quota_project_id
+ )
+ # Don't apply audience if the credentials file passed from user.
+ if hasattr(credentials, "with_gdch_audience"):
+ credentials = credentials.with_gdch_audience(
+ api_audience if api_audience else host
+ )
+
+ # If the credentials are service account credentials, then always try to use self signed JWT.
+ if (
+ always_use_jwt_access
+ and isinstance(credentials, service_account.Credentials)
+ and hasattr(service_account.Credentials, "with_always_use_jwt_access")
+ ):
+ credentials = credentials.with_always_use_jwt_access(True)
+
+ # Save the credentials.
+ self._credentials = credentials
+
+ # Save the hostname. Default to port 443 (HTTPS) if none is specified.
+ if ":" not in host:
+ host += ":443"
+ self._host = host
+
+ def _prep_wrapped_messages(self, client_info):
+ # Precompute the wrapped methods.
+ self._wrapped_methods = {
+ self.create_subscription: gapic_v1.method.wrap_method(
+ self.create_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.get_subscription: gapic_v1.method.wrap_method(
+ self.get_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.update_subscription: gapic_v1.method.wrap_method(
+ self.update_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.list_subscriptions: gapic_v1.method.wrap_method(
+ self.list_subscriptions,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.delete_subscription: gapic_v1.method.wrap_method(
+ self.delete_subscription,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.modify_ack_deadline: gapic_v1.method.wrap_method(
+ self.modify_ack_deadline,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.acknowledge: gapic_v1.method.wrap_method(
+ self.acknowledge,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.pull: gapic_v1.method.wrap_method(
+ self.pull,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.streaming_pull: gapic_v1.method.wrap_method(
+ self.streaming_pull,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.DeadlineExceeded,
+ core_exceptions.InternalServerError,
+ core_exceptions.ResourceExhausted,
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=900.0,
+ ),
+ default_timeout=900.0,
+ client_info=client_info,
+ ),
+ self.modify_push_config: gapic_v1.method.wrap_method(
+ self.modify_push_config,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.get_snapshot: gapic_v1.method.wrap_method(
+ self.get_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.list_snapshots: gapic_v1.method.wrap_method(
+ self.list_snapshots,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.create_snapshot: gapic_v1.method.wrap_method(
+ self.create_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.update_snapshot: gapic_v1.method.wrap_method(
+ self.update_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.delete_snapshot: gapic_v1.method.wrap_method(
+ self.delete_snapshot,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.ServiceUnavailable,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ self.seek: gapic_v1.method.wrap_method(
+ self.seek,
+ default_retry=retries.Retry(
+ initial=0.1,
+ maximum=60.0,
+ multiplier=1.3,
+ predicate=retries.if_exception_type(
+ core_exceptions.Aborted,
+ core_exceptions.ServiceUnavailable,
+ core_exceptions.Unknown,
+ ),
+ deadline=60.0,
+ ),
+ default_timeout=60.0,
+ client_info=client_info,
+ ),
+ }
+
+ def close(self):
+ """Closes resources associated with the transport.
+
+ .. warning::
+ Only call this method if the transport is NOT shared
+ with other clients - this may cause errors in other clients!
+ """
+ raise NotImplementedError()
+
+ @property
+ def create_subscription(
+ self,
+ ) -> Callable[
+ [pubsub.Subscription],
+ Union[pubsub.Subscription, Awaitable[pubsub.Subscription]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def get_subscription(
+ self,
+ ) -> Callable[
+ [pubsub.GetSubscriptionRequest],
+ Union[pubsub.Subscription, Awaitable[pubsub.Subscription]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def update_subscription(
+ self,
+ ) -> Callable[
+ [pubsub.UpdateSubscriptionRequest],
+ Union[pubsub.Subscription, Awaitable[pubsub.Subscription]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def list_subscriptions(
+ self,
+ ) -> Callable[
+ [pubsub.ListSubscriptionsRequest],
+ Union[
+ pubsub.ListSubscriptionsResponse,
+ Awaitable[pubsub.ListSubscriptionsResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def delete_subscription(
+ self,
+ ) -> Callable[
+ [pubsub.DeleteSubscriptionRequest],
+ Union[empty_pb2.Empty, Awaitable[empty_pb2.Empty]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def modify_ack_deadline(
+ self,
+ ) -> Callable[
+ [pubsub.ModifyAckDeadlineRequest],
+ Union[empty_pb2.Empty, Awaitable[empty_pb2.Empty]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def acknowledge(
+ self,
+ ) -> Callable[
+ [pubsub.AcknowledgeRequest], Union[empty_pb2.Empty, Awaitable[empty_pb2.Empty]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def pull(
+ self,
+ ) -> Callable[
+ [pubsub.PullRequest], Union[pubsub.PullResponse, Awaitable[pubsub.PullResponse]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def streaming_pull(
+ self,
+ ) -> Callable[
+ [pubsub.StreamingPullRequest],
+ Union[pubsub.StreamingPullResponse, Awaitable[pubsub.StreamingPullResponse]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def modify_push_config(
+ self,
+ ) -> Callable[
+ [pubsub.ModifyPushConfigRequest],
+ Union[empty_pb2.Empty, Awaitable[empty_pb2.Empty]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def get_snapshot(
+ self,
+ ) -> Callable[
+ [pubsub.GetSnapshotRequest], Union[pubsub.Snapshot, Awaitable[pubsub.Snapshot]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def list_snapshots(
+ self,
+ ) -> Callable[
+ [pubsub.ListSnapshotsRequest],
+ Union[pubsub.ListSnapshotsResponse, Awaitable[pubsub.ListSnapshotsResponse]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def create_snapshot(
+ self,
+ ) -> Callable[
+ [pubsub.CreateSnapshotRequest],
+ Union[pubsub.Snapshot, Awaitable[pubsub.Snapshot]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def update_snapshot(
+ self,
+ ) -> Callable[
+ [pubsub.UpdateSnapshotRequest],
+ Union[pubsub.Snapshot, Awaitable[pubsub.Snapshot]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def delete_snapshot(
+ self,
+ ) -> Callable[
+ [pubsub.DeleteSnapshotRequest],
+ Union[empty_pb2.Empty, Awaitable[empty_pb2.Empty]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def seek(
+ self,
+ ) -> Callable[
+ [pubsub.SeekRequest], Union[pubsub.SeekResponse, Awaitable[pubsub.SeekResponse]]
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.SetIamPolicyRequest],
+ Union[policy_pb2.Policy, Awaitable[policy_pb2.Policy]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.GetIamPolicyRequest],
+ Union[policy_pb2.Policy, Awaitable[policy_pb2.Policy]],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ Union[
+ iam_policy_pb2.TestIamPermissionsResponse,
+ Awaitable[iam_policy_pb2.TestIamPermissionsResponse],
+ ],
+ ]:
+ raise NotImplementedError()
+
+ @property
+ def kind(self) -> str:
+ raise NotImplementedError()
+
+
+__all__ = ("SubscriberTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/grpc.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/grpc.py
new file mode 100644
index 000000000000..5954b6403343
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/grpc.py
@@ -0,0 +1,834 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import warnings
+from typing import Callable, Dict, Optional, Sequence, Tuple, Union
+
+from google.api_core import grpc_helpers
+from google.api_core import gapic_v1
+import google.auth # type: ignore
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+
+import grpc # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import pubsub
+from .base import SubscriberTransport, DEFAULT_CLIENT_INFO
+
+
+class SubscriberGrpcTransport(SubscriberTransport):
+ """gRPC backend transport for Subscriber.
+
+ The service that an application uses to manipulate subscriptions and
+ to consume messages from a subscription via the ``Pull`` method or
+ by establishing a bi-directional stream using the ``StreamingPull``
+ method.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _stubs: Dict[str, Callable]
+
+ def __init__(
+ self,
+ *,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Sequence[str] = None,
+ channel: grpc.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id: Optional[str] = None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional(Sequence[str])): A list of scopes. This argument is
+ ignored if ``channel`` is provided.
+ channel (Optional[grpc.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTLSChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ("grpc.max_metadata_size", 4 * 1024 * 1024),
+ ("grpc.keepalive_time_ms", 30000),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: str = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> grpc.Channel:
+ """Create and return a gRPC channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is mutually exclusive with credentials.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ grpc.Channel: A gRPC channel object.
+
+ Raises:
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+
+ return grpc_helpers.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ @property
+ def grpc_channel(self) -> grpc.Channel:
+ """Return the channel designed to connect to this service."""
+ return self._grpc_channel
+
+ @property
+ def create_subscription(
+ self,
+ ) -> Callable[[pubsub.Subscription], pubsub.Subscription]:
+ r"""Return a callable for the create subscription method over gRPC.
+
+ Creates a subscription to a given topic. See the [resource name
+ rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). If
+ the subscription already exists, returns ``ALREADY_EXISTS``. If
+ the corresponding topic doesn't exist, returns ``NOT_FOUND``.
+
+ If the name is not provided in the request, the server will
+ assign a random name for this subscription on the same project
+ as the topic, conforming to the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Subscription object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ Returns:
+ Callable[[~.Subscription],
+ ~.Subscription]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_subscription" not in self._stubs:
+ self._stubs["create_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/CreateSubscription",
+ request_serializer=pubsub.Subscription.serialize,
+ response_deserializer=pubsub.Subscription.deserialize,
+ )
+ return self._stubs["create_subscription"]
+
+ @property
+ def get_subscription(
+ self,
+ ) -> Callable[[pubsub.GetSubscriptionRequest], pubsub.Subscription]:
+ r"""Return a callable for the get subscription method over gRPC.
+
+ Gets the configuration details of a subscription.
+
+ Returns:
+ Callable[[~.GetSubscriptionRequest],
+ ~.Subscription]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_subscription" not in self._stubs:
+ self._stubs["get_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/GetSubscription",
+ request_serializer=pubsub.GetSubscriptionRequest.serialize,
+ response_deserializer=pubsub.Subscription.deserialize,
+ )
+ return self._stubs["get_subscription"]
+
+ @property
+ def update_subscription(
+ self,
+ ) -> Callable[[pubsub.UpdateSubscriptionRequest], pubsub.Subscription]:
+ r"""Return a callable for the update subscription method over gRPC.
+
+ Updates an existing subscription. Note that certain
+ properties of a subscription, such as its topic, are not
+ modifiable.
+
+ Returns:
+ Callable[[~.UpdateSubscriptionRequest],
+ ~.Subscription]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "update_subscription" not in self._stubs:
+ self._stubs["update_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/UpdateSubscription",
+ request_serializer=pubsub.UpdateSubscriptionRequest.serialize,
+ response_deserializer=pubsub.Subscription.deserialize,
+ )
+ return self._stubs["update_subscription"]
+
+ @property
+ def list_subscriptions(
+ self,
+ ) -> Callable[[pubsub.ListSubscriptionsRequest], pubsub.ListSubscriptionsResponse]:
+ r"""Return a callable for the list subscriptions method over gRPC.
+
+ Lists matching subscriptions.
+
+ Returns:
+ Callable[[~.ListSubscriptionsRequest],
+ ~.ListSubscriptionsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_subscriptions" not in self._stubs:
+ self._stubs["list_subscriptions"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ListSubscriptions",
+ request_serializer=pubsub.ListSubscriptionsRequest.serialize,
+ response_deserializer=pubsub.ListSubscriptionsResponse.deserialize,
+ )
+ return self._stubs["list_subscriptions"]
+
+ @property
+ def delete_subscription(
+ self,
+ ) -> Callable[[pubsub.DeleteSubscriptionRequest], empty_pb2.Empty]:
+ r"""Return a callable for the delete subscription method over gRPC.
+
+ Deletes an existing subscription. All messages retained in the
+ subscription are immediately dropped. Calls to ``Pull`` after
+ deletion will return ``NOT_FOUND``. After a subscription is
+ deleted, a new one may be created with the same name, but the
+ new one has no association with the old subscription or its
+ topic unless the same topic is specified.
+
+ Returns:
+ Callable[[~.DeleteSubscriptionRequest],
+ ~.Empty]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_subscription" not in self._stubs:
+ self._stubs["delete_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/DeleteSubscription",
+ request_serializer=pubsub.DeleteSubscriptionRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_subscription"]
+
+ @property
+ def modify_ack_deadline(
+ self,
+ ) -> Callable[[pubsub.ModifyAckDeadlineRequest], empty_pb2.Empty]:
+ r"""Return a callable for the modify ack deadline method over gRPC.
+
+ Modifies the ack deadline for a specific message. This method is
+ useful to indicate that more time is needed to process a message
+ by the subscriber, or to make the message available for
+ redelivery if the processing was interrupted. Note that this
+ does not modify the subscription-level ``ackDeadlineSeconds``
+ used for subsequent messages.
+
+ Returns:
+ Callable[[~.ModifyAckDeadlineRequest],
+ ~.Empty]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "modify_ack_deadline" not in self._stubs:
+ self._stubs["modify_ack_deadline"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ModifyAckDeadline",
+ request_serializer=pubsub.ModifyAckDeadlineRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["modify_ack_deadline"]
+
+ @property
+ def acknowledge(self) -> Callable[[pubsub.AcknowledgeRequest], empty_pb2.Empty]:
+ r"""Return a callable for the acknowledge method over gRPC.
+
+ Acknowledges the messages associated with the ``ack_ids`` in the
+ ``AcknowledgeRequest``. The Pub/Sub system can remove the
+ relevant messages from the subscription.
+
+ Acknowledging a message whose ack deadline has expired may
+ succeed, but such a message may be redelivered later.
+ Acknowledging a message more than once will not result in an
+ error.
+
+ Returns:
+ Callable[[~.AcknowledgeRequest],
+ ~.Empty]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "acknowledge" not in self._stubs:
+ self._stubs["acknowledge"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/Acknowledge",
+ request_serializer=pubsub.AcknowledgeRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["acknowledge"]
+
+ @property
+ def pull(self) -> Callable[[pubsub.PullRequest], pubsub.PullResponse]:
+ r"""Return a callable for the pull method over gRPC.
+
+ Pulls messages from the server. The server may return
+ ``UNAVAILABLE`` if there are too many concurrent pull requests
+ pending for the given subscription.
+
+ Returns:
+ Callable[[~.PullRequest],
+ ~.PullResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "pull" not in self._stubs:
+ self._stubs["pull"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/Pull",
+ request_serializer=pubsub.PullRequest.serialize,
+ response_deserializer=pubsub.PullResponse.deserialize,
+ )
+ return self._stubs["pull"]
+
+ @property
+ def streaming_pull(
+ self,
+ ) -> Callable[[pubsub.StreamingPullRequest], pubsub.StreamingPullResponse]:
+ r"""Return a callable for the streaming pull method over gRPC.
+
+ Establishes a stream with the server, which sends messages down
+ to the client. The client streams acknowledgements and ack
+ deadline modifications back to the server. The server will close
+ the stream and return the status on any error. The server may
+ close the stream with status ``UNAVAILABLE`` to reassign
+ server-side resources, in which case, the client should
+ re-establish the stream. Flow control can be achieved by
+ configuring the underlying RPC channel.
+
+ Returns:
+ Callable[[~.StreamingPullRequest],
+ ~.StreamingPullResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "streaming_pull" not in self._stubs:
+ self._stubs["streaming_pull"] = self.grpc_channel.stream_stream(
+ "/google.pubsub.v1.Subscriber/StreamingPull",
+ request_serializer=pubsub.StreamingPullRequest.serialize,
+ response_deserializer=pubsub.StreamingPullResponse.deserialize,
+ )
+ return self._stubs["streaming_pull"]
+
+ @property
+ def modify_push_config(
+ self,
+ ) -> Callable[[pubsub.ModifyPushConfigRequest], empty_pb2.Empty]:
+ r"""Return a callable for the modify push config method over gRPC.
+
+ Modifies the ``PushConfig`` for a specified subscription.
+
+ This may be used to change a push subscription to a pull one
+ (signified by an empty ``PushConfig``) or vice versa, or change
+ the endpoint URL and other attributes of a push subscription.
+ Messages will accumulate for delivery continuously through the
+ call regardless of changes to the ``PushConfig``.
+
+ Returns:
+ Callable[[~.ModifyPushConfigRequest],
+ ~.Empty]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "modify_push_config" not in self._stubs:
+ self._stubs["modify_push_config"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ModifyPushConfig",
+ request_serializer=pubsub.ModifyPushConfigRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["modify_push_config"]
+
+ @property
+ def get_snapshot(self) -> Callable[[pubsub.GetSnapshotRequest], pubsub.Snapshot]:
+ r"""Return a callable for the get snapshot method over gRPC.
+
+ Gets the configuration details of a snapshot.
+ Snapshots are used in Seek
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ Returns:
+ Callable[[~.GetSnapshotRequest],
+ ~.Snapshot]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_snapshot" not in self._stubs:
+ self._stubs["get_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/GetSnapshot",
+ request_serializer=pubsub.GetSnapshotRequest.serialize,
+ response_deserializer=pubsub.Snapshot.deserialize,
+ )
+ return self._stubs["get_snapshot"]
+
+ @property
+ def list_snapshots(
+ self,
+ ) -> Callable[[pubsub.ListSnapshotsRequest], pubsub.ListSnapshotsResponse]:
+ r"""Return a callable for the list snapshots method over gRPC.
+
+ Lists the existing snapshots. Snapshots are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ Returns:
+ Callable[[~.ListSnapshotsRequest],
+ ~.ListSnapshotsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_snapshots" not in self._stubs:
+ self._stubs["list_snapshots"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ListSnapshots",
+ request_serializer=pubsub.ListSnapshotsRequest.serialize,
+ response_deserializer=pubsub.ListSnapshotsResponse.deserialize,
+ )
+ return self._stubs["list_snapshots"]
+
+ @property
+ def create_snapshot(
+ self,
+ ) -> Callable[[pubsub.CreateSnapshotRequest], pubsub.Snapshot]:
+ r"""Return a callable for the create snapshot method over gRPC.
+
+ Creates a snapshot from the requested subscription. Snapshots
+ are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ If the snapshot already exists, returns ``ALREADY_EXISTS``. If
+ the requested subscription doesn't exist, returns ``NOT_FOUND``.
+ If the backlog in the subscription is too old -- and the
+ resulting snapshot would expire in less than 1 hour -- then
+ ``FAILED_PRECONDITION`` is returned. See also the
+ ``Snapshot.expire_time`` field. If the name is not provided in
+ the request, the server will assign a random name for this
+ snapshot on the same project as the subscription, conforming to
+ the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Snapshot object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ Returns:
+ Callable[[~.CreateSnapshotRequest],
+ ~.Snapshot]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_snapshot" not in self._stubs:
+ self._stubs["create_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/CreateSnapshot",
+ request_serializer=pubsub.CreateSnapshotRequest.serialize,
+ response_deserializer=pubsub.Snapshot.deserialize,
+ )
+ return self._stubs["create_snapshot"]
+
+ @property
+ def update_snapshot(
+ self,
+ ) -> Callable[[pubsub.UpdateSnapshotRequest], pubsub.Snapshot]:
+ r"""Return a callable for the update snapshot method over gRPC.
+
+ Updates an existing snapshot. Snapshots are used in
+ Seek
+ operations, which allow
+ you to manage message acknowledgments in bulk. That is,
+ you can set the acknowledgment state of messages in an
+ existing subscription to the state captured by a
+ snapshot.
+
+ Returns:
+ Callable[[~.UpdateSnapshotRequest],
+ ~.Snapshot]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "update_snapshot" not in self._stubs:
+ self._stubs["update_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/UpdateSnapshot",
+ request_serializer=pubsub.UpdateSnapshotRequest.serialize,
+ response_deserializer=pubsub.Snapshot.deserialize,
+ )
+ return self._stubs["update_snapshot"]
+
+ @property
+ def delete_snapshot(
+ self,
+ ) -> Callable[[pubsub.DeleteSnapshotRequest], empty_pb2.Empty]:
+ r"""Return a callable for the delete snapshot method over gRPC.
+
+ Removes an existing snapshot. Snapshots are used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ When the snapshot is deleted, all messages retained in the
+ snapshot are immediately dropped. After a snapshot is deleted, a
+ new one may be created with the same name, but the new one has
+ no association with the old snapshot or its subscription, unless
+ the same subscription is specified.
+
+ Returns:
+ Callable[[~.DeleteSnapshotRequest],
+ ~.Empty]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_snapshot" not in self._stubs:
+ self._stubs["delete_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/DeleteSnapshot",
+ request_serializer=pubsub.DeleteSnapshotRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_snapshot"]
+
+ @property
+ def seek(self) -> Callable[[pubsub.SeekRequest], pubsub.SeekResponse]:
+ r"""Return a callable for the seek method over gRPC.
+
+ Seeks an existing subscription to a point in time or to a given
+ snapshot, whichever is provided in the request. Snapshots are
+ used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ Note that both the subscription and the snapshot must be on the
+ same topic.
+
+ Returns:
+ Callable[[~.SeekRequest],
+ ~.SeekResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "seek" not in self._stubs:
+ self._stubs["seek"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/Seek",
+ request_serializer=pubsub.SeekRequest.serialize,
+ response_deserializer=pubsub.SeekResponse.deserialize,
+ )
+ return self._stubs["seek"]
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], policy_pb2.Policy]:
+ r"""Return a callable for the set iam policy method over gRPC.
+ Sets the IAM access control policy on the specified
+ function. Replaces any existing policy.
+ Returns:
+ Callable[[~.SetIamPolicyRequest],
+ ~.Policy]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "set_iam_policy" not in self._stubs:
+ self._stubs["set_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/SetIamPolicy",
+ request_serializer=iam_policy_pb2.SetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["set_iam_policy"]
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], policy_pb2.Policy]:
+ r"""Return a callable for the get iam policy method over gRPC.
+ Gets the IAM access control policy for a function.
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+ Returns:
+ Callable[[~.GetIamPolicyRequest],
+ ~.Policy]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_iam_policy" not in self._stubs:
+ self._stubs["get_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/GetIamPolicy",
+ request_serializer=iam_policy_pb2.GetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["get_iam_policy"]
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ iam_policy_pb2.TestIamPermissionsResponse,
+ ]:
+ r"""Return a callable for the test iam permissions method over gRPC.
+ Tests the specified permissions against the IAM access control
+ policy for a function. If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+ Returns:
+ Callable[[~.TestIamPermissionsRequest],
+ ~.TestIamPermissionsResponse]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "test_iam_permissions" not in self._stubs:
+ self._stubs["test_iam_permissions"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/TestIamPermissions",
+ request_serializer=iam_policy_pb2.TestIamPermissionsRequest.SerializeToString,
+ response_deserializer=iam_policy_pb2.TestIamPermissionsResponse.FromString,
+ )
+ return self._stubs["test_iam_permissions"]
+
+ def close(self):
+ self.grpc_channel.close()
+
+ @property
+ def kind(self) -> str:
+ return "grpc"
+
+
+__all__ = ("SubscriberGrpcTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/grpc_asyncio.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/grpc_asyncio.py
new file mode 100644
index 000000000000..778e49c5dc8e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/transports/grpc_asyncio.py
@@ -0,0 +1,843 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import warnings
+from typing import Awaitable, Callable, Dict, Optional, Sequence, Tuple, Union
+
+from google.api_core import gapic_v1
+from google.api_core import grpc_helpers_async
+from google.auth import credentials as ga_credentials # type: ignore
+from google.auth.transport.grpc import SslCredentials # type: ignore
+
+import grpc # type: ignore
+from grpc.experimental import aio # type: ignore
+
+from google.iam.v1 import iam_policy_pb2 # type: ignore
+from google.iam.v1 import policy_pb2 # type: ignore
+from google.protobuf import empty_pb2 # type: ignore
+from google.pubsub_v1.types import pubsub
+from .base import SubscriberTransport, DEFAULT_CLIENT_INFO
+from .grpc import SubscriberGrpcTransport
+
+
+class SubscriberGrpcAsyncIOTransport(SubscriberTransport):
+ """gRPC AsyncIO backend transport for Subscriber.
+
+ The service that an application uses to manipulate subscriptions and
+ to consume messages from a subscription via the ``Pull`` method or
+ by establishing a bi-directional stream using the ``StreamingPull``
+ method.
+
+ This class defines the same methods as the primary client, so the
+ primary client can load the underlying transport implementation
+ and call it.
+
+ It sends protocol buffers over the wire using gRPC (which is built on
+ top of HTTP/2); the ``grpcio`` package must be installed.
+ """
+
+ _grpc_channel: aio.Channel
+ _stubs: Dict[str, Callable] = {}
+
+ @classmethod
+ def create_channel(
+ cls,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ quota_project_id: Optional[str] = None,
+ **kwargs,
+ ) -> aio.Channel:
+ """Create and return a gRPC AsyncIO channel object.
+ Args:
+ host (Optional[str]): The host for the channel to use.
+ credentials (Optional[~.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain
+ the credentials from the environment.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ kwargs (Optional[dict]): Keyword arguments, which are passed to the
+ channel creation.
+ Returns:
+ aio.Channel: A gRPC AsyncIO channel object.
+ """
+
+ return grpc_helpers_async.create_channel(
+ host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ quota_project_id=quota_project_id,
+ default_scopes=cls.AUTH_SCOPES,
+ scopes=scopes,
+ default_host=cls.DEFAULT_HOST,
+ **kwargs,
+ )
+
+ def __init__(
+ self,
+ *,
+ host: str = "pubsub.googleapis.com",
+ credentials: ga_credentials.Credentials = None,
+ credentials_file: Optional[str] = None,
+ scopes: Optional[Sequence[str]] = None,
+ channel: aio.Channel = None,
+ api_mtls_endpoint: str = None,
+ client_cert_source: Callable[[], Tuple[bytes, bytes]] = None,
+ ssl_channel_credentials: grpc.ChannelCredentials = None,
+ client_cert_source_for_mtls: Callable[[], Tuple[bytes, bytes]] = None,
+ quota_project_id=None,
+ client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+ always_use_jwt_access: Optional[bool] = False,
+ api_audience: Optional[str] = None,
+ ) -> None:
+ """Instantiate the transport.
+
+ Args:
+ host (Optional[str]):
+ The hostname to connect to.
+ credentials (Optional[google.auth.credentials.Credentials]): The
+ authorization credentials to attach to requests. These
+ credentials identify the application to the service; if none
+ are specified, the client will attempt to ascertain the
+ credentials from the environment.
+ This argument is ignored if ``channel`` is provided.
+ credentials_file (Optional[str]): A file with credentials that can
+ be loaded with :func:`google.auth.load_credentials_from_file`.
+ This argument is ignored if ``channel`` is provided.
+ scopes (Optional[Sequence[str]]): A optional list of scopes needed for this
+ service. These are only used when credentials are not specified and
+ are passed to :func:`google.auth.default`.
+ channel (Optional[aio.Channel]): A ``Channel`` instance through
+ which to make calls.
+ api_mtls_endpoint (Optional[str]): Deprecated. The mutual TLS endpoint.
+ If provided, it overrides the ``host`` argument and tries to create
+ a mutual TLS channel with client SSL credentials from
+ ``client_cert_source`` or application default SSL credentials.
+ client_cert_source (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ Deprecated. A callback to provide client SSL certificate bytes and
+ private key bytes, both in PEM format. It is ignored if
+ ``api_mtls_endpoint`` is None.
+ ssl_channel_credentials (grpc.ChannelCredentials): SSL credentials
+ for the grpc channel. It is ignored if ``channel`` is provided.
+ client_cert_source_for_mtls (Optional[Callable[[], Tuple[bytes, bytes]]]):
+ A callback to provide client certificate bytes and private key bytes,
+ both in PEM format. It is used to configure a mutual TLS channel. It is
+ ignored if ``channel`` or ``ssl_channel_credentials`` is provided.
+ quota_project_id (Optional[str]): An optional project to use for billing
+ and quota.
+ client_info (google.api_core.gapic_v1.client_info.ClientInfo):
+ The client info used to send a user-agent string along with
+ API requests. If ``None``, then default info will be used.
+ Generally, you only need to set this if you're developing
+ your own client library.
+ always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+ be used for service account credentials.
+
+ Raises:
+ google.auth.exceptions.MutualTlsChannelError: If mutual TLS transport
+ creation failed for any reason.
+ google.api_core.exceptions.DuplicateCredentialArgs: If both ``credentials``
+ and ``credentials_file`` are passed.
+ """
+ self._grpc_channel = None
+ self._ssl_channel_credentials = ssl_channel_credentials
+ self._stubs: Dict[str, Callable] = {}
+
+ if api_mtls_endpoint:
+ warnings.warn("api_mtls_endpoint is deprecated", DeprecationWarning)
+ if client_cert_source:
+ warnings.warn("client_cert_source is deprecated", DeprecationWarning)
+
+ if channel:
+ # Ignore credentials if a channel was passed.
+ credentials = False
+ # If a channel was explicitly provided, set it.
+ self._grpc_channel = channel
+ self._ssl_channel_credentials = None
+ else:
+ if api_mtls_endpoint:
+ host = api_mtls_endpoint
+
+ # Create SSL credentials with client_cert_source or application
+ # default SSL credentials.
+ if client_cert_source:
+ cert, key = client_cert_source()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+ else:
+ self._ssl_channel_credentials = SslCredentials().ssl_credentials
+
+ else:
+ if client_cert_source_for_mtls and not ssl_channel_credentials:
+ cert, key = client_cert_source_for_mtls()
+ self._ssl_channel_credentials = grpc.ssl_channel_credentials(
+ certificate_chain=cert, private_key=key
+ )
+
+ # The base transport sets the host, credentials and scopes
+ super().__init__(
+ host=host,
+ credentials=credentials,
+ credentials_file=credentials_file,
+ scopes=scopes,
+ quota_project_id=quota_project_id,
+ client_info=client_info,
+ always_use_jwt_access=always_use_jwt_access,
+ api_audience=api_audience,
+ )
+
+ if not self._grpc_channel:
+ self._grpc_channel = type(self).create_channel(
+ self._host,
+ # use the credentials which are saved
+ credentials=self._credentials,
+ # Set ``credentials_file`` to ``None`` here as
+ # the credentials that we saved earlier should be used.
+ credentials_file=None,
+ scopes=self._scopes,
+ ssl_credentials=self._ssl_channel_credentials,
+ quota_project_id=quota_project_id,
+ options=[
+ ("grpc.max_send_message_length", -1),
+ ("grpc.max_receive_message_length", -1),
+ ("grpc.max_metadata_size", 4 * 1024 * 1024),
+ ("grpc.keepalive_time_ms", 30000),
+ ],
+ )
+
+ # Wrap messages. This must be done after self._grpc_channel exists
+ self._prep_wrapped_messages(client_info)
+
+ @property
+ def grpc_channel(self) -> aio.Channel:
+ """Create the channel designed to connect to this service.
+
+ This property caches on the instance; repeated calls return
+ the same channel.
+ """
+ # Return the channel from cache.
+ return self._grpc_channel
+
+ @property
+ def create_subscription(
+ self,
+ ) -> Callable[[pubsub.Subscription], Awaitable[pubsub.Subscription]]:
+ r"""Return a callable for the create subscription method over gRPC.
+
+ Creates a subscription to a given topic. See the [resource name
+ rules]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). If
+ the subscription already exists, returns ``ALREADY_EXISTS``. If
+ the corresponding topic doesn't exist, returns ``NOT_FOUND``.
+
+ If the name is not provided in the request, the server will
+ assign a random name for this subscription on the same project
+ as the topic, conforming to the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Subscription object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ Returns:
+ Callable[[~.Subscription],
+ Awaitable[~.Subscription]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_subscription" not in self._stubs:
+ self._stubs["create_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/CreateSubscription",
+ request_serializer=pubsub.Subscription.serialize,
+ response_deserializer=pubsub.Subscription.deserialize,
+ )
+ return self._stubs["create_subscription"]
+
+ @property
+ def get_subscription(
+ self,
+ ) -> Callable[[pubsub.GetSubscriptionRequest], Awaitable[pubsub.Subscription]]:
+ r"""Return a callable for the get subscription method over gRPC.
+
+ Gets the configuration details of a subscription.
+
+ Returns:
+ Callable[[~.GetSubscriptionRequest],
+ Awaitable[~.Subscription]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_subscription" not in self._stubs:
+ self._stubs["get_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/GetSubscription",
+ request_serializer=pubsub.GetSubscriptionRequest.serialize,
+ response_deserializer=pubsub.Subscription.deserialize,
+ )
+ return self._stubs["get_subscription"]
+
+ @property
+ def update_subscription(
+ self,
+ ) -> Callable[[pubsub.UpdateSubscriptionRequest], Awaitable[pubsub.Subscription]]:
+ r"""Return a callable for the update subscription method over gRPC.
+
+ Updates an existing subscription. Note that certain
+ properties of a subscription, such as its topic, are not
+ modifiable.
+
+ Returns:
+ Callable[[~.UpdateSubscriptionRequest],
+ Awaitable[~.Subscription]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "update_subscription" not in self._stubs:
+ self._stubs["update_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/UpdateSubscription",
+ request_serializer=pubsub.UpdateSubscriptionRequest.serialize,
+ response_deserializer=pubsub.Subscription.deserialize,
+ )
+ return self._stubs["update_subscription"]
+
+ @property
+ def list_subscriptions(
+ self,
+ ) -> Callable[
+ [pubsub.ListSubscriptionsRequest], Awaitable[pubsub.ListSubscriptionsResponse]
+ ]:
+ r"""Return a callable for the list subscriptions method over gRPC.
+
+ Lists matching subscriptions.
+
+ Returns:
+ Callable[[~.ListSubscriptionsRequest],
+ Awaitable[~.ListSubscriptionsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_subscriptions" not in self._stubs:
+ self._stubs["list_subscriptions"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ListSubscriptions",
+ request_serializer=pubsub.ListSubscriptionsRequest.serialize,
+ response_deserializer=pubsub.ListSubscriptionsResponse.deserialize,
+ )
+ return self._stubs["list_subscriptions"]
+
+ @property
+ def delete_subscription(
+ self,
+ ) -> Callable[[pubsub.DeleteSubscriptionRequest], Awaitable[empty_pb2.Empty]]:
+ r"""Return a callable for the delete subscription method over gRPC.
+
+ Deletes an existing subscription. All messages retained in the
+ subscription are immediately dropped. Calls to ``Pull`` after
+ deletion will return ``NOT_FOUND``. After a subscription is
+ deleted, a new one may be created with the same name, but the
+ new one has no association with the old subscription or its
+ topic unless the same topic is specified.
+
+ Returns:
+ Callable[[~.DeleteSubscriptionRequest],
+ Awaitable[~.Empty]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_subscription" not in self._stubs:
+ self._stubs["delete_subscription"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/DeleteSubscription",
+ request_serializer=pubsub.DeleteSubscriptionRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_subscription"]
+
+ @property
+ def modify_ack_deadline(
+ self,
+ ) -> Callable[[pubsub.ModifyAckDeadlineRequest], Awaitable[empty_pb2.Empty]]:
+ r"""Return a callable for the modify ack deadline method over gRPC.
+
+ Modifies the ack deadline for a specific message. This method is
+ useful to indicate that more time is needed to process a message
+ by the subscriber, or to make the message available for
+ redelivery if the processing was interrupted. Note that this
+ does not modify the subscription-level ``ackDeadlineSeconds``
+ used for subsequent messages.
+
+ Returns:
+ Callable[[~.ModifyAckDeadlineRequest],
+ Awaitable[~.Empty]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "modify_ack_deadline" not in self._stubs:
+ self._stubs["modify_ack_deadline"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ModifyAckDeadline",
+ request_serializer=pubsub.ModifyAckDeadlineRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["modify_ack_deadline"]
+
+ @property
+ def acknowledge(
+ self,
+ ) -> Callable[[pubsub.AcknowledgeRequest], Awaitable[empty_pb2.Empty]]:
+ r"""Return a callable for the acknowledge method over gRPC.
+
+ Acknowledges the messages associated with the ``ack_ids`` in the
+ ``AcknowledgeRequest``. The Pub/Sub system can remove the
+ relevant messages from the subscription.
+
+ Acknowledging a message whose ack deadline has expired may
+ succeed, but such a message may be redelivered later.
+ Acknowledging a message more than once will not result in an
+ error.
+
+ Returns:
+ Callable[[~.AcknowledgeRequest],
+ Awaitable[~.Empty]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "acknowledge" not in self._stubs:
+ self._stubs["acknowledge"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/Acknowledge",
+ request_serializer=pubsub.AcknowledgeRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["acknowledge"]
+
+ @property
+ def pull(self) -> Callable[[pubsub.PullRequest], Awaitable[pubsub.PullResponse]]:
+ r"""Return a callable for the pull method over gRPC.
+
+ Pulls messages from the server. The server may return
+ ``UNAVAILABLE`` if there are too many concurrent pull requests
+ pending for the given subscription.
+
+ Returns:
+ Callable[[~.PullRequest],
+ Awaitable[~.PullResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "pull" not in self._stubs:
+ self._stubs["pull"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/Pull",
+ request_serializer=pubsub.PullRequest.serialize,
+ response_deserializer=pubsub.PullResponse.deserialize,
+ )
+ return self._stubs["pull"]
+
+ @property
+ def streaming_pull(
+ self,
+ ) -> Callable[
+ [pubsub.StreamingPullRequest], Awaitable[pubsub.StreamingPullResponse]
+ ]:
+ r"""Return a callable for the streaming pull method over gRPC.
+
+ Establishes a stream with the server, which sends messages down
+ to the client. The client streams acknowledgements and ack
+ deadline modifications back to the server. The server will close
+ the stream and return the status on any error. The server may
+ close the stream with status ``UNAVAILABLE`` to reassign
+ server-side resources, in which case, the client should
+ re-establish the stream. Flow control can be achieved by
+ configuring the underlying RPC channel.
+
+ Returns:
+ Callable[[~.StreamingPullRequest],
+ Awaitable[~.StreamingPullResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "streaming_pull" not in self._stubs:
+ self._stubs["streaming_pull"] = self.grpc_channel.stream_stream(
+ "/google.pubsub.v1.Subscriber/StreamingPull",
+ request_serializer=pubsub.StreamingPullRequest.serialize,
+ response_deserializer=pubsub.StreamingPullResponse.deserialize,
+ )
+ return self._stubs["streaming_pull"]
+
+ @property
+ def modify_push_config(
+ self,
+ ) -> Callable[[pubsub.ModifyPushConfigRequest], Awaitable[empty_pb2.Empty]]:
+ r"""Return a callable for the modify push config method over gRPC.
+
+ Modifies the ``PushConfig`` for a specified subscription.
+
+ This may be used to change a push subscription to a pull one
+ (signified by an empty ``PushConfig``) or vice versa, or change
+ the endpoint URL and other attributes of a push subscription.
+ Messages will accumulate for delivery continuously through the
+ call regardless of changes to the ``PushConfig``.
+
+ Returns:
+ Callable[[~.ModifyPushConfigRequest],
+ Awaitable[~.Empty]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "modify_push_config" not in self._stubs:
+ self._stubs["modify_push_config"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ModifyPushConfig",
+ request_serializer=pubsub.ModifyPushConfigRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["modify_push_config"]
+
+ @property
+ def get_snapshot(
+ self,
+ ) -> Callable[[pubsub.GetSnapshotRequest], Awaitable[pubsub.Snapshot]]:
+ r"""Return a callable for the get snapshot method over gRPC.
+
+ Gets the configuration details of a snapshot.
+ Snapshots are used in Seek
+ operations, which allow you to manage message
+ acknowledgments in bulk. That is, you can set the
+ acknowledgment state of messages in an existing
+ subscription to the state captured by a snapshot.
+
+ Returns:
+ Callable[[~.GetSnapshotRequest],
+ Awaitable[~.Snapshot]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_snapshot" not in self._stubs:
+ self._stubs["get_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/GetSnapshot",
+ request_serializer=pubsub.GetSnapshotRequest.serialize,
+ response_deserializer=pubsub.Snapshot.deserialize,
+ )
+ return self._stubs["get_snapshot"]
+
+ @property
+ def list_snapshots(
+ self,
+ ) -> Callable[
+ [pubsub.ListSnapshotsRequest], Awaitable[pubsub.ListSnapshotsResponse]
+ ]:
+ r"""Return a callable for the list snapshots method over gRPC.
+
+ Lists the existing snapshots. Snapshots are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+
+ Returns:
+ Callable[[~.ListSnapshotsRequest],
+ Awaitable[~.ListSnapshotsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "list_snapshots" not in self._stubs:
+ self._stubs["list_snapshots"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/ListSnapshots",
+ request_serializer=pubsub.ListSnapshotsRequest.serialize,
+ response_deserializer=pubsub.ListSnapshotsResponse.deserialize,
+ )
+ return self._stubs["list_snapshots"]
+
+ @property
+ def create_snapshot(
+ self,
+ ) -> Callable[[pubsub.CreateSnapshotRequest], Awaitable[pubsub.Snapshot]]:
+ r"""Return a callable for the create snapshot method over gRPC.
+
+ Creates a snapshot from the requested subscription. Snapshots
+ are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ If the snapshot already exists, returns ``ALREADY_EXISTS``. If
+ the requested subscription doesn't exist, returns ``NOT_FOUND``.
+ If the backlog in the subscription is too old -- and the
+ resulting snapshot would expire in less than 1 hour -- then
+ ``FAILED_PRECONDITION`` is returned. See also the
+ ``Snapshot.expire_time`` field. If the name is not provided in
+ the request, the server will assign a random name for this
+ snapshot on the same project as the subscription, conforming to
+ the [resource name format]
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). The
+ generated name is populated in the returned Snapshot object.
+ Note that for REST API requests, you must specify a name in the
+ request.
+
+ Returns:
+ Callable[[~.CreateSnapshotRequest],
+ Awaitable[~.Snapshot]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "create_snapshot" not in self._stubs:
+ self._stubs["create_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/CreateSnapshot",
+ request_serializer=pubsub.CreateSnapshotRequest.serialize,
+ response_deserializer=pubsub.Snapshot.deserialize,
+ )
+ return self._stubs["create_snapshot"]
+
+ @property
+ def update_snapshot(
+ self,
+ ) -> Callable[[pubsub.UpdateSnapshotRequest], Awaitable[pubsub.Snapshot]]:
+ r"""Return a callable for the update snapshot method over gRPC.
+
+ Updates an existing snapshot. Snapshots are used in
+ Seek
+ operations, which allow
+ you to manage message acknowledgments in bulk. That is,
+ you can set the acknowledgment state of messages in an
+ existing subscription to the state captured by a
+ snapshot.
+
+ Returns:
+ Callable[[~.UpdateSnapshotRequest],
+ Awaitable[~.Snapshot]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "update_snapshot" not in self._stubs:
+ self._stubs["update_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/UpdateSnapshot",
+ request_serializer=pubsub.UpdateSnapshotRequest.serialize,
+ response_deserializer=pubsub.Snapshot.deserialize,
+ )
+ return self._stubs["update_snapshot"]
+
+ @property
+ def delete_snapshot(
+ self,
+ ) -> Callable[[pubsub.DeleteSnapshotRequest], Awaitable[empty_pb2.Empty]]:
+ r"""Return a callable for the delete snapshot method over gRPC.
+
+ Removes an existing snapshot. Snapshots are used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ When the snapshot is deleted, all messages retained in the
+ snapshot are immediately dropped. After a snapshot is deleted, a
+ new one may be created with the same name, but the new one has
+ no association with the old snapshot or its subscription, unless
+ the same subscription is specified.
+
+ Returns:
+ Callable[[~.DeleteSnapshotRequest],
+ Awaitable[~.Empty]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "delete_snapshot" not in self._stubs:
+ self._stubs["delete_snapshot"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/DeleteSnapshot",
+ request_serializer=pubsub.DeleteSnapshotRequest.serialize,
+ response_deserializer=empty_pb2.Empty.FromString,
+ )
+ return self._stubs["delete_snapshot"]
+
+ @property
+ def seek(self) -> Callable[[pubsub.SeekRequest], Awaitable[pubsub.SeekResponse]]:
+ r"""Return a callable for the seek method over gRPC.
+
+ Seeks an existing subscription to a point in time or to a given
+ snapshot, whichever is provided in the request. Snapshots are
+ used in [Seek]
+ (https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages
+ in an existing subscription to the state captured by a snapshot.
+ Note that both the subscription and the snapshot must be on the
+ same topic.
+
+ Returns:
+ Callable[[~.SeekRequest],
+ Awaitable[~.SeekResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "seek" not in self._stubs:
+ self._stubs["seek"] = self.grpc_channel.unary_unary(
+ "/google.pubsub.v1.Subscriber/Seek",
+ request_serializer=pubsub.SeekRequest.serialize,
+ response_deserializer=pubsub.SeekResponse.deserialize,
+ )
+ return self._stubs["seek"]
+
+ @property
+ def set_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.SetIamPolicyRequest], Awaitable[policy_pb2.Policy]]:
+ r"""Return a callable for the set iam policy method over gRPC.
+ Sets the IAM access control policy on the specified
+ function. Replaces any existing policy.
+ Returns:
+ Callable[[~.SetIamPolicyRequest],
+ Awaitable[~.Policy]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "set_iam_policy" not in self._stubs:
+ self._stubs["set_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/SetIamPolicy",
+ request_serializer=iam_policy_pb2.SetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["set_iam_policy"]
+
+ @property
+ def get_iam_policy(
+ self,
+ ) -> Callable[[iam_policy_pb2.GetIamPolicyRequest], Awaitable[policy_pb2.Policy]]:
+ r"""Return a callable for the get iam policy method over gRPC.
+ Gets the IAM access control policy for a function.
+ Returns an empty policy if the function exists and does
+ not have a policy set.
+ Returns:
+ Callable[[~.GetIamPolicyRequest],
+ Awaitable[~.Policy]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "get_iam_policy" not in self._stubs:
+ self._stubs["get_iam_policy"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/GetIamPolicy",
+ request_serializer=iam_policy_pb2.GetIamPolicyRequest.SerializeToString,
+ response_deserializer=policy_pb2.Policy.FromString,
+ )
+ return self._stubs["get_iam_policy"]
+
+ @property
+ def test_iam_permissions(
+ self,
+ ) -> Callable[
+ [iam_policy_pb2.TestIamPermissionsRequest],
+ Awaitable[iam_policy_pb2.TestIamPermissionsResponse],
+ ]:
+ r"""Return a callable for the test iam permissions method over gRPC.
+ Tests the specified permissions against the IAM access control
+ policy for a function. If the function does not exist, this will
+ return an empty set of permissions, not a NOT_FOUND error.
+ Returns:
+ Callable[[~.TestIamPermissionsRequest],
+ Awaitable[~.TestIamPermissionsResponse]]:
+ A function that, when called, will call the underlying RPC
+ on the server.
+ """
+ # Generate a "stub function" on-the-fly which will actually make
+ # the request.
+ # gRPC handles serialization and deserialization, so we just need
+ # to pass in the functions for each.
+ if "test_iam_permissions" not in self._stubs:
+ self._stubs["test_iam_permissions"] = self.grpc_channel.unary_unary(
+ "/google.iam.v1.IAMPolicy/TestIamPermissions",
+ request_serializer=iam_policy_pb2.TestIamPermissionsRequest.SerializeToString,
+ response_deserializer=iam_policy_pb2.TestIamPermissionsResponse.FromString,
+ )
+ return self._stubs["test_iam_permissions"]
+
+ def close(self):
+ return self.grpc_channel.close()
+
+
+__all__ = ("SubscriberGrpcAsyncIOTransport",)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/__init__.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/__init__.py
new file mode 100644
index 000000000000..c0d9c4619d75
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/__init__.py
@@ -0,0 +1,147 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from typing import Union
+
+from .pubsub import (
+ AcknowledgeRequest,
+ BigQueryConfig,
+ CreateSnapshotRequest,
+ DeadLetterPolicy,
+ DeleteSnapshotRequest,
+ DeleteSubscriptionRequest,
+ DeleteTopicRequest,
+ DetachSubscriptionRequest,
+ DetachSubscriptionResponse,
+ ExpirationPolicy,
+ GetSnapshotRequest,
+ GetSubscriptionRequest,
+ GetTopicRequest,
+ ListSnapshotsRequest,
+ ListSnapshotsResponse,
+ ListSubscriptionsRequest,
+ ListSubscriptionsResponse,
+ ListTopicSnapshotsRequest,
+ ListTopicSnapshotsResponse,
+ ListTopicsRequest,
+ ListTopicsResponse,
+ ListTopicSubscriptionsRequest,
+ ListTopicSubscriptionsResponse,
+ MessageStoragePolicy,
+ ModifyAckDeadlineRequest,
+ ModifyPushConfigRequest,
+ PublishRequest,
+ PublishResponse,
+ PubsubMessage,
+ PullRequest,
+ PullResponse,
+ PushConfig,
+ ReceivedMessage,
+ RetryPolicy,
+ SchemaSettings,
+ SeekRequest,
+ SeekResponse,
+ Snapshot,
+ StreamingPullRequest,
+ StreamingPullResponse,
+ Subscription,
+ Topic,
+ UpdateSnapshotRequest,
+ UpdateSubscriptionRequest,
+ UpdateTopicRequest,
+)
+from .schema import (
+ CreateSchemaRequest,
+ DeleteSchemaRequest,
+ GetSchemaRequest,
+ ListSchemasRequest,
+ ListSchemasResponse,
+ Schema,
+ ValidateMessageRequest,
+ ValidateMessageResponse,
+ ValidateSchemaRequest,
+ ValidateSchemaResponse,
+ Encoding,
+ SchemaView,
+)
+
+TimeoutType = Union[
+ int,
+ float,
+ "google.api_core.timeout.ConstantTimeout",
+ "google.api_core.timeout.ExponentialTimeout",
+]
+"""The type of the timeout parameter of publisher client methods."""
+
+__all__ = (
+ "TimeoutType",
+ "AcknowledgeRequest",
+ "BigQueryConfig",
+ "CreateSnapshotRequest",
+ "DeadLetterPolicy",
+ "DeleteSnapshotRequest",
+ "DeleteSubscriptionRequest",
+ "DeleteTopicRequest",
+ "DetachSubscriptionRequest",
+ "DetachSubscriptionResponse",
+ "ExpirationPolicy",
+ "GetSnapshotRequest",
+ "GetSubscriptionRequest",
+ "GetTopicRequest",
+ "ListSnapshotsRequest",
+ "ListSnapshotsResponse",
+ "ListSubscriptionsRequest",
+ "ListSubscriptionsResponse",
+ "ListTopicSnapshotsRequest",
+ "ListTopicSnapshotsResponse",
+ "ListTopicsRequest",
+ "ListTopicsResponse",
+ "ListTopicSubscriptionsRequest",
+ "ListTopicSubscriptionsResponse",
+ "MessageStoragePolicy",
+ "ModifyAckDeadlineRequest",
+ "ModifyPushConfigRequest",
+ "PublishRequest",
+ "PublishResponse",
+ "PubsubMessage",
+ "PullRequest",
+ "PullResponse",
+ "PushConfig",
+ "ReceivedMessage",
+ "RetryPolicy",
+ "SchemaSettings",
+ "SeekRequest",
+ "SeekResponse",
+ "Snapshot",
+ "StreamingPullRequest",
+ "StreamingPullResponse",
+ "Subscription",
+ "Topic",
+ "UpdateSnapshotRequest",
+ "UpdateSubscriptionRequest",
+ "UpdateTopicRequest",
+ "CreateSchemaRequest",
+ "DeleteSchemaRequest",
+ "GetSchemaRequest",
+ "ListSchemasRequest",
+ "ListSchemasResponse",
+ "Schema",
+ "ValidateMessageRequest",
+ "ValidateMessageResponse",
+ "ValidateSchemaRequest",
+ "ValidateSchemaResponse",
+ "Encoding",
+ "SchemaView",
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
new file mode 100644
index 000000000000..73658e9c0989
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
@@ -0,0 +1,1867 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import proto # type: ignore
+
+from google.protobuf import duration_pb2 # type: ignore
+from google.protobuf import field_mask_pb2 # type: ignore
+from google.protobuf import timestamp_pb2 # type: ignore
+from google.pubsub_v1.types import schema as gp_schema
+
+
+__protobuf__ = proto.module(
+ package="google.pubsub.v1",
+ manifest={
+ "MessageStoragePolicy",
+ "SchemaSettings",
+ "Topic",
+ "PubsubMessage",
+ "GetTopicRequest",
+ "UpdateTopicRequest",
+ "PublishRequest",
+ "PublishResponse",
+ "ListTopicsRequest",
+ "ListTopicsResponse",
+ "ListTopicSubscriptionsRequest",
+ "ListTopicSubscriptionsResponse",
+ "ListTopicSnapshotsRequest",
+ "ListTopicSnapshotsResponse",
+ "DeleteTopicRequest",
+ "DetachSubscriptionRequest",
+ "DetachSubscriptionResponse",
+ "Subscription",
+ "RetryPolicy",
+ "DeadLetterPolicy",
+ "ExpirationPolicy",
+ "PushConfig",
+ "BigQueryConfig",
+ "ReceivedMessage",
+ "GetSubscriptionRequest",
+ "UpdateSubscriptionRequest",
+ "ListSubscriptionsRequest",
+ "ListSubscriptionsResponse",
+ "DeleteSubscriptionRequest",
+ "ModifyPushConfigRequest",
+ "PullRequest",
+ "PullResponse",
+ "ModifyAckDeadlineRequest",
+ "AcknowledgeRequest",
+ "StreamingPullRequest",
+ "StreamingPullResponse",
+ "CreateSnapshotRequest",
+ "UpdateSnapshotRequest",
+ "Snapshot",
+ "GetSnapshotRequest",
+ "ListSnapshotsRequest",
+ "ListSnapshotsResponse",
+ "DeleteSnapshotRequest",
+ "SeekRequest",
+ "SeekResponse",
+ },
+)
+
+
+class MessageStoragePolicy(proto.Message):
+ r"""A policy constraining the storage of messages published to
+ the topic.
+
+ Attributes:
+ allowed_persistence_regions (Sequence[str]):
+ A list of IDs of GCP regions where messages
+ that are published to the topic may be persisted
+ in storage. Messages published by publishers
+ running in non-allowed GCP regions (or running
+ outside of GCP altogether) will be routed for
+ storage in one of the allowed regions. An empty
+ list means that no regions are allowed, and is
+ not a valid configuration.
+ """
+
+ allowed_persistence_regions = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+
+
+class SchemaSettings(proto.Message):
+ r"""Settings for validating messages published against a schema.
+
+ Attributes:
+ schema (str):
+ Required. The name of the schema that messages published
+ should be validated against. Format is
+ ``projects/{project}/schemas/{schema}``. The value of this
+ field will be ``_deleted-schema_`` if the schema has been
+ deleted.
+ encoding (google.pubsub_v1.types.Encoding):
+ The encoding of messages validated against ``schema``.
+ """
+
+ schema = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ encoding = proto.Field(
+ proto.ENUM,
+ number=2,
+ enum=gp_schema.Encoding,
+ )
+
+
+class Topic(proto.Message):
+ r"""A topic resource.
+
+ Attributes:
+ name (str):
+ Required. The name of the topic. It must have the format
+ ``"projects/{project}/topics/{topic}"``. ``{topic}`` must
+ start with a letter, and contain only letters
+ (``[A-Za-z]``), numbers (``[0-9]``), dashes (``-``),
+ underscores (``_``), periods (``.``), tildes (``~``), plus
+ (``+``) or percent signs (``%``). It must be between 3 and
+ 255 characters in length, and it must not start with
+ ``"goog"``.
+ labels (Mapping[str, str]):
+ See [Creating and managing labels]
+ (https://cloud.google.com/pubsub/docs/labels).
+ message_storage_policy (google.pubsub_v1.types.MessageStoragePolicy):
+ Policy constraining the set of Google Cloud
+ Platform regions where messages published to the
+ topic may be stored. If not present, then no
+ constraints are in effect.
+ kms_key_name (str):
+ The resource name of the Cloud KMS CryptoKey to be used to
+ protect access to messages published on this topic.
+
+ The expected format is
+ ``projects/*/locations/*/keyRings/*/cryptoKeys/*``.
+ schema_settings (google.pubsub_v1.types.SchemaSettings):
+ Settings for validating messages published
+ against a schema.
+ satisfies_pzs (bool):
+ Reserved for future use. This field is set
+ only in responses from the server; it is ignored
+ if it is set in any requests.
+ message_retention_duration (google.protobuf.duration_pb2.Duration):
+ Indicates the minimum duration to retain a message after it
+ is published to the topic. If this field is set, messages
+ published to the topic in the last
+ ``message_retention_duration`` are always available to
+ subscribers. For instance, it allows any attached
+ subscription to `seek to a
+ timestamp `__
+ that is up to ``message_retention_duration`` in the past. If
+ this field is not set, message retention is controlled by
+ settings on individual subscriptions. Cannot be more than 7
+ days or less than 10 minutes.
+ """
+
+ name = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ labels = proto.MapField(
+ proto.STRING,
+ proto.STRING,
+ number=2,
+ )
+ message_storage_policy = proto.Field(
+ proto.MESSAGE,
+ number=3,
+ message="MessageStoragePolicy",
+ )
+ kms_key_name = proto.Field(
+ proto.STRING,
+ number=5,
+ )
+ schema_settings = proto.Field(
+ proto.MESSAGE,
+ number=6,
+ message="SchemaSettings",
+ )
+ satisfies_pzs = proto.Field(
+ proto.BOOL,
+ number=7,
+ )
+ message_retention_duration = proto.Field(
+ proto.MESSAGE,
+ number=8,
+ message=duration_pb2.Duration,
+ )
+
+
+class PubsubMessage(proto.Message):
+ r"""A message that is published by publishers and consumed by
+ subscribers. The message must contain either a non-empty data field
+ or at least one attribute. Note that client libraries represent this
+ object differently depending on the language. See the corresponding
+ `client library
+ documentation `__
+ for more information. See [quotas and limits]
+ (https://cloud.google.com/pubsub/quotas) for more information about
+ message limits.
+
+ Attributes:
+ data (bytes):
+ The message data field. If this field is
+ empty, the message must contain at least one
+ attribute.
+ attributes (Mapping[str, str]):
+ Attributes for this message. If this field is
+ empty, the message must contain non-empty data.
+ This can be used to filter messages on the
+ subscription.
+ message_id (str):
+ ID of this message, assigned by the server when the message
+ is published. Guaranteed to be unique within the topic. This
+ value may be read by a subscriber that receives a
+ ``PubsubMessage`` via a ``Pull`` call or a push delivery. It
+ must not be populated by the publisher in a ``Publish``
+ call.
+ publish_time (google.protobuf.timestamp_pb2.Timestamp):
+ The time at which the message was published, populated by
+ the server when it receives the ``Publish`` call. It must
+ not be populated by the publisher in a ``Publish`` call.
+ ordering_key (str):
+ If non-empty, identifies related messages for which publish
+ order should be respected. If a ``Subscription`` has
+ ``enable_message_ordering`` set to ``true``, messages
+ published with the same non-empty ``ordering_key`` value
+ will be delivered to subscribers in the order in which they
+ are received by the Pub/Sub system. All ``PubsubMessage``\ s
+ published in a given ``PublishRequest`` must specify the
+ same ``ordering_key`` value.
+ """
+
+ data = proto.Field(
+ proto.BYTES,
+ number=1,
+ )
+ attributes = proto.MapField(
+ proto.STRING,
+ proto.STRING,
+ number=2,
+ )
+ message_id = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+ publish_time = proto.Field(
+ proto.MESSAGE,
+ number=4,
+ message=timestamp_pb2.Timestamp,
+ )
+ ordering_key = proto.Field(
+ proto.STRING,
+ number=5,
+ )
+
+
+class GetTopicRequest(proto.Message):
+ r"""Request for the GetTopic method.
+
+ Attributes:
+ topic (str):
+ Required. The name of the topic to get. Format is
+ ``projects/{project}/topics/{topic}``.
+ """
+
+ topic = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class UpdateTopicRequest(proto.Message):
+ r"""Request for the UpdateTopic method.
+
+ Attributes:
+ topic (google.pubsub_v1.types.Topic):
+ Required. The updated topic object.
+ update_mask (google.protobuf.field_mask_pb2.FieldMask):
+ Required. Indicates which fields in the provided topic to
+ update. Must be specified and non-empty. Note that if
+ ``update_mask`` contains "message_storage_policy" but the
+ ``message_storage_policy`` is not set in the ``topic``
+ provided above, then the updated value is determined by the
+ policy configured at the project or organization level.
+ """
+
+ topic = proto.Field(
+ proto.MESSAGE,
+ number=1,
+ message="Topic",
+ )
+ update_mask = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message=field_mask_pb2.FieldMask,
+ )
+
+
+class PublishRequest(proto.Message):
+ r"""Request for the Publish method.
+
+ Attributes:
+ topic (str):
+ Required. The messages in the request will be published on
+ this topic. Format is ``projects/{project}/topics/{topic}``.
+ messages (Sequence[google.pubsub_v1.types.PubsubMessage]):
+ Required. The messages to publish.
+ """
+
+ topic = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ messages = proto.RepeatedField(
+ proto.MESSAGE,
+ number=2,
+ message="PubsubMessage",
+ )
+
+
+class PublishResponse(proto.Message):
+ r"""Response for the ``Publish`` method.
+
+ Attributes:
+ message_ids (Sequence[str]):
+ The server-assigned ID of each published
+ message, in the same order as the messages in
+ the request. IDs are guaranteed to be unique
+ within the topic.
+ """
+
+ message_ids = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+
+
+class ListTopicsRequest(proto.Message):
+ r"""Request for the ``ListTopics`` method.
+
+ Attributes:
+ project (str):
+ Required. The name of the project in which to list topics.
+ Format is ``projects/{project-id}``.
+ page_size (int):
+ Maximum number of topics to return.
+ page_token (str):
+ The value returned by the last ``ListTopicsResponse``;
+ indicates that this is a continuation of a prior
+ ``ListTopics`` call, and that the system should return the
+ next page of data.
+ """
+
+ project = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ page_size = proto.Field(
+ proto.INT32,
+ number=2,
+ )
+ page_token = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+
+
+class ListTopicsResponse(proto.Message):
+ r"""Response for the ``ListTopics`` method.
+
+ Attributes:
+ topics (Sequence[google.pubsub_v1.types.Topic]):
+ The resulting topics.
+ next_page_token (str):
+ If not empty, indicates that there may be more topics that
+ match the request; this value should be passed in a new
+ ``ListTopicsRequest``.
+ """
+
+ @property
+ def raw_page(self):
+ return self
+
+ topics = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="Topic",
+ )
+ next_page_token = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+
+
+class ListTopicSubscriptionsRequest(proto.Message):
+ r"""Request for the ``ListTopicSubscriptions`` method.
+
+ Attributes:
+ topic (str):
+ Required. The name of the topic that subscriptions are
+ attached to. Format is
+ ``projects/{project}/topics/{topic}``.
+ page_size (int):
+ Maximum number of subscription names to
+ return.
+ page_token (str):
+ The value returned by the last
+ ``ListTopicSubscriptionsResponse``; indicates that this is a
+ continuation of a prior ``ListTopicSubscriptions`` call, and
+ that the system should return the next page of data.
+ """
+
+ topic = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ page_size = proto.Field(
+ proto.INT32,
+ number=2,
+ )
+ page_token = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+
+
+class ListTopicSubscriptionsResponse(proto.Message):
+ r"""Response for the ``ListTopicSubscriptions`` method.
+
+ Attributes:
+ subscriptions (Sequence[str]):
+ The names of subscriptions attached to the
+ topic specified in the request.
+ next_page_token (str):
+ If not empty, indicates that there may be more subscriptions
+ that match the request; this value should be passed in a new
+ ``ListTopicSubscriptionsRequest`` to get more subscriptions.
+ """
+
+ @property
+ def raw_page(self):
+ return self
+
+ subscriptions = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+ next_page_token = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+
+
+class ListTopicSnapshotsRequest(proto.Message):
+ r"""Request for the ``ListTopicSnapshots`` method.
+
+ Attributes:
+ topic (str):
+ Required. The name of the topic that snapshots are attached
+ to. Format is ``projects/{project}/topics/{topic}``.
+ page_size (int):
+ Maximum number of snapshot names to return.
+ page_token (str):
+ The value returned by the last
+ ``ListTopicSnapshotsResponse``; indicates that this is a
+ continuation of a prior ``ListTopicSnapshots`` call, and
+ that the system should return the next page of data.
+ """
+
+ topic = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ page_size = proto.Field(
+ proto.INT32,
+ number=2,
+ )
+ page_token = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+
+
+class ListTopicSnapshotsResponse(proto.Message):
+ r"""Response for the ``ListTopicSnapshots`` method.
+
+ Attributes:
+ snapshots (Sequence[str]):
+ The names of the snapshots that match the
+ request.
+ next_page_token (str):
+ If not empty, indicates that there may be more snapshots
+ that match the request; this value should be passed in a new
+ ``ListTopicSnapshotsRequest`` to get more snapshots.
+ """
+
+ @property
+ def raw_page(self):
+ return self
+
+ snapshots = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+ next_page_token = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+
+
+class DeleteTopicRequest(proto.Message):
+ r"""Request for the ``DeleteTopic`` method.
+
+ Attributes:
+ topic (str):
+ Required. Name of the topic to delete. Format is
+ ``projects/{project}/topics/{topic}``.
+ """
+
+ topic = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class DetachSubscriptionRequest(proto.Message):
+ r"""Request for the DetachSubscription method.
+
+ Attributes:
+ subscription (str):
+ Required. The subscription to detach. Format is
+ ``projects/{project}/subscriptions/{subscription}``.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class DetachSubscriptionResponse(proto.Message):
+ r"""Response for the DetachSubscription method.
+ Reserved for future use.
+
+ """
+
+
+class Subscription(proto.Message):
+ r"""A subscription resource.
+
+ Attributes:
+ name (str):
+ Required. The name of the subscription. It must have the
+ format
+ ``"projects/{project}/subscriptions/{subscription}"``.
+ ``{subscription}`` must start with a letter, and contain
+ only letters (``[A-Za-z]``), numbers (``[0-9]``), dashes
+ (``-``), underscores (``_``), periods (``.``), tildes
+ (``~``), plus (``+``) or percent signs (``%``). It must be
+ between 3 and 255 characters in length, and it must not
+ start with ``"goog"``.
+ topic (str):
+ Required. The name of the topic from which this subscription
+ is receiving messages. Format is
+ ``projects/{project}/topics/{topic}``. The value of this
+ field will be ``_deleted-topic_`` if the topic has been
+ deleted.
+ push_config (google.pubsub_v1.types.PushConfig):
+ If push delivery is used with this subscription, this field
+ is used to configure it. Either ``pushConfig`` or
+ ``bigQueryConfig`` can be set, but not both. If both are
+ empty, then the subscriber will pull and ack messages using
+ API methods.
+ bigquery_config (google.pubsub_v1.types.BigQueryConfig):
+ If delivery to BigQuery is used with this subscription, this
+ field is used to configure it. Either ``pushConfig`` or
+ ``bigQueryConfig`` can be set, but not both. If both are
+ empty, then the subscriber will pull and ack messages using
+ API methods.
+ ack_deadline_seconds (int):
+ The approximate amount of time (on a best-effort basis)
+ Pub/Sub waits for the subscriber to acknowledge receipt
+ before resending the message. In the interval after the
+ message is delivered and before it is acknowledged, it is
+ considered to be outstanding. During that time period, the
+ message will not be redelivered (on a best-effort basis).
+
+ For pull subscriptions, this value is used as the initial
+ value for the ack deadline. To override this value for a
+ given message, call ``ModifyAckDeadline`` with the
+ corresponding ``ack_id`` if using non-streaming pull or send
+ the ``ack_id`` in a ``StreamingModifyAckDeadlineRequest`` if
+ using streaming pull. The minimum custom deadline you can
+ specify is 10 seconds. The maximum custom deadline you can
+ specify is 600 seconds (10 minutes). If this parameter is 0,
+ a default value of 10 seconds is used.
+
+ For push delivery, this value is also used to set the
+ request timeout for the call to the push endpoint.
+
+ If the subscriber never acknowledges the message, the
+ Pub/Sub system will eventually redeliver the message.
+ retain_acked_messages (bool):
+ Indicates whether to retain acknowledged messages. If true,
+ then messages are not expunged from the subscription's
+ backlog, even if they are acknowledged, until they fall out
+ of the ``message_retention_duration`` window. This must be
+ true if you would like to [``Seek`` to a timestamp]
+ (https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)
+ in the past to replay previously-acknowledged messages.
+ message_retention_duration (google.protobuf.duration_pb2.Duration):
+ How long to retain unacknowledged messages in the
+ subscription's backlog, from the moment a message is
+ published. If ``retain_acked_messages`` is true, then this
+ also configures the retention of acknowledged messages, and
+ thus configures how far back in time a ``Seek`` can be done.
+ Defaults to 7 days. Cannot be more than 7 days or less than
+ 10 minutes.
+ labels (Mapping[str, str]):
+ See
+ Creating and managing labels .
+ enable_message_ordering (bool):
+ If true, messages published with the same ``ordering_key``
+ in ``PubsubMessage`` will be delivered to the subscribers in
+ the order in which they are received by the Pub/Sub system.
+ Otherwise, they may be delivered in any order.
+ expiration_policy (google.pubsub_v1.types.ExpirationPolicy):
+ A policy that specifies the conditions for this
+ subscription's expiration. A subscription is considered
+ active as long as any connected subscriber is successfully
+ consuming messages from the subscription or is issuing
+ operations on the subscription. If ``expiration_policy`` is
+ not set, a *default policy* with ``ttl`` of 31 days will be
+ used. The minimum allowed value for
+ ``expiration_policy.ttl`` is 1 day.
+ filter (str):
+ An expression written in the Pub/Sub `filter
+ language `__.
+ If non-empty, then only ``PubsubMessage``\ s whose
+ ``attributes`` field matches the filter are delivered on
+ this subscription. If empty, then no messages are filtered
+ out.
+ dead_letter_policy (google.pubsub_v1.types.DeadLetterPolicy):
+ A policy that specifies the conditions for dead lettering
+ messages in this subscription. If dead_letter_policy is not
+ set, dead lettering is disabled.
+
+ The Cloud Pub/Sub service account associated with this
+ subscriptions's parent project (i.e.,
+ service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com)
+ must have permission to Acknowledge() messages on this
+ subscription.
+ retry_policy (google.pubsub_v1.types.RetryPolicy):
+ A policy that specifies how Pub/Sub retries
+ message delivery for this subscription.
+
+ If not set, the default retry policy is applied.
+ This generally implies that messages will be
+ retried as soon as possible for healthy
+ subscribers. RetryPolicy will be triggered on
+ NACKs or acknowledgement deadline exceeded
+ events for a given message.
+ detached (bool):
+ Indicates whether the subscription is detached from its
+ topic. Detached subscriptions don't receive messages from
+ their topic and don't retain any backlog. ``Pull`` and
+ ``StreamingPull`` requests will return FAILED_PRECONDITION.
+ If the subscription is a push subscription, pushes to the
+ endpoint will not be made.
+ enable_exactly_once_delivery (bool):
+ If true, Pub/Sub provides the following guarantees for the
+ delivery of a message with a given value of ``message_id``
+ on this subscription:
+
+ - The message sent to a subscriber is guaranteed not to be
+ resent before the message's acknowledgement deadline
+ expires.
+ - An acknowledged message will not be resent to a
+ subscriber.
+
+ Note that subscribers may still receive multiple copies of a
+ message when ``enable_exactly_once_delivery`` is true if the
+ message was published multiple times by a publisher client.
+ These copies are considered distinct by Pub/Sub and have
+ distinct ``message_id`` values.
+ topic_message_retention_duration (google.protobuf.duration_pb2.Duration):
+ Output only. Indicates the minimum duration for which a
+ message is retained after it is published to the
+ subscription's topic. If this field is set, messages
+ published to the subscription's topic in the last
+ ``topic_message_retention_duration`` are always available to
+ subscribers. See the ``message_retention_duration`` field in
+ ``Topic``. This field is set only in responses from the
+ server; it is ignored if it is set in any requests.
+ state (google.pubsub_v1.types.Subscription.State):
+ Output only. An output-only field indicating
+ whether or not the subscription can receive
+ messages.
+ """
+
+ class State(proto.Enum):
+ r"""Possible states for a subscription."""
+ STATE_UNSPECIFIED = 0
+ ACTIVE = 1
+ RESOURCE_ERROR = 2
+
+ name = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ topic = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+ push_config = proto.Field(
+ proto.MESSAGE,
+ number=4,
+ message="PushConfig",
+ )
+ bigquery_config = proto.Field(
+ proto.MESSAGE,
+ number=18,
+ message="BigQueryConfig",
+ )
+ ack_deadline_seconds = proto.Field(
+ proto.INT32,
+ number=5,
+ )
+ retain_acked_messages = proto.Field(
+ proto.BOOL,
+ number=7,
+ )
+ message_retention_duration = proto.Field(
+ proto.MESSAGE,
+ number=8,
+ message=duration_pb2.Duration,
+ )
+ labels = proto.MapField(
+ proto.STRING,
+ proto.STRING,
+ number=9,
+ )
+ enable_message_ordering = proto.Field(
+ proto.BOOL,
+ number=10,
+ )
+ expiration_policy = proto.Field(
+ proto.MESSAGE,
+ number=11,
+ message="ExpirationPolicy",
+ )
+ filter = proto.Field(
+ proto.STRING,
+ number=12,
+ )
+ dead_letter_policy = proto.Field(
+ proto.MESSAGE,
+ number=13,
+ message="DeadLetterPolicy",
+ )
+ retry_policy = proto.Field(
+ proto.MESSAGE,
+ number=14,
+ message="RetryPolicy",
+ )
+ detached = proto.Field(
+ proto.BOOL,
+ number=15,
+ )
+ enable_exactly_once_delivery = proto.Field(
+ proto.BOOL,
+ number=16,
+ )
+ topic_message_retention_duration = proto.Field(
+ proto.MESSAGE,
+ number=17,
+ message=duration_pb2.Duration,
+ )
+ state = proto.Field(
+ proto.ENUM,
+ number=19,
+ enum=State,
+ )
+
+
+class RetryPolicy(proto.Message):
+ r"""A policy that specifies how Cloud Pub/Sub retries message delivery.
+
+ Retry delay will be exponential based on provided minimum and
+ maximum backoffs. https://en.wikipedia.org/wiki/Exponential_backoff.
+
+ RetryPolicy will be triggered on NACKs or acknowledgement deadline
+ exceeded events for a given message.
+
+ Retry Policy is implemented on a best effort basis. At times, the
+ delay between consecutive deliveries may not match the
+ configuration. That is, delay can be more or less than configured
+ backoff.
+
+ Attributes:
+ minimum_backoff (google.protobuf.duration_pb2.Duration):
+ The minimum delay between consecutive
+ deliveries of a given message. Value should be
+ between 0 and 600 seconds. Defaults to 10
+ seconds.
+ maximum_backoff (google.protobuf.duration_pb2.Duration):
+ The maximum delay between consecutive
+ deliveries of a given message. Value should be
+ between 0 and 600 seconds. Defaults to 600
+ seconds.
+ """
+
+ minimum_backoff = proto.Field(
+ proto.MESSAGE,
+ number=1,
+ message=duration_pb2.Duration,
+ )
+ maximum_backoff = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message=duration_pb2.Duration,
+ )
+
+
+class DeadLetterPolicy(proto.Message):
+ r"""Dead lettering is done on a best effort basis. The same
+ message might be dead lettered multiple times.
+
+ If validation on any of the fields fails at subscription
+ creation/updation, the create/update subscription request will
+ fail.
+
+ Attributes:
+ dead_letter_topic (str):
+ The name of the topic to which dead letter messages should
+ be published. Format is
+ ``projects/{project}/topics/{topic}``.The Cloud Pub/Sub
+ service account associated with the enclosing subscription's
+ parent project (i.e.,
+ service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com)
+ must have permission to Publish() to this topic.
+
+ The operation will fail if the topic does not exist. Users
+ should ensure that there is a subscription attached to this
+ topic since messages published to a topic with no
+ subscriptions are lost.
+ max_delivery_attempts (int):
+ The maximum number of delivery attempts for any message. The
+ value must be between 5 and 100.
+
+ The number of delivery attempts is defined as 1 + (the sum
+ of number of NACKs and number of times the acknowledgement
+ deadline has been exceeded for the message).
+
+ A NACK is any call to ModifyAckDeadline with a 0 deadline.
+ Note that client libraries may automatically extend
+ ack_deadlines.
+
+ This field will be honored on a best effort basis.
+
+ If this parameter is 0, a default value of 5 is used.
+ """
+
+ dead_letter_topic = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ max_delivery_attempts = proto.Field(
+ proto.INT32,
+ number=2,
+ )
+
+
+class ExpirationPolicy(proto.Message):
+ r"""A policy that specifies the conditions for resource
+ expiration (i.e., automatic resource deletion).
+
+ Attributes:
+ ttl (google.protobuf.duration_pb2.Duration):
+ Specifies the "time-to-live" duration for an associated
+ resource. The resource expires if it is not active for a
+ period of ``ttl``. The definition of "activity" depends on
+ the type of the associated resource. The minimum and maximum
+ allowed values for ``ttl`` depend on the type of the
+ associated resource, as well. If ``ttl`` is not set, the
+ associated resource never expires.
+ """
+
+ ttl = proto.Field(
+ proto.MESSAGE,
+ number=1,
+ message=duration_pb2.Duration,
+ )
+
+
+class PushConfig(proto.Message):
+ r"""Configuration for a push delivery endpoint.
+
+ .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+ Attributes:
+ push_endpoint (str):
+ A URL locating the endpoint to which messages should be
+ pushed. For example, a Webhook endpoint might use
+ ``https://example.com/push``.
+ attributes (Mapping[str, str]):
+ Endpoint configuration attributes that can be used to
+ control different aspects of the message delivery.
+
+ The only currently supported attribute is
+ ``x-goog-version``, which you can use to change the format
+ of the pushed message. This attribute indicates the version
+ of the data expected by the endpoint. This controls the
+ shape of the pushed message (i.e., its fields and metadata).
+
+ If not present during the ``CreateSubscription`` call, it
+ will default to the version of the Pub/Sub API used to make
+ such call. If not present in a ``ModifyPushConfig`` call,
+ its value will not be changed. ``GetSubscription`` calls
+ will always return a valid version, even if the subscription
+ was created without this attribute.
+
+ The only supported values for the ``x-goog-version``
+ attribute are:
+
+ - ``v1beta1``: uses the push format defined in the v1beta1
+ Pub/Sub API.
+ - ``v1`` or ``v1beta2``: uses the push format defined in
+ the v1 Pub/Sub API.
+
+ For example:
+
+ .. raw:: html
+
+ attributes { "x-goog-version": "v1" } `__.
+
+ Attributes:
+ service_account_email (str):
+ `Service account
+ email `__
+ to be used for generating the OIDC token. The caller (for
+ CreateSubscription, UpdateSubscription, and ModifyPushConfig
+ RPCs) must have the iam.serviceAccounts.actAs permission for
+ the service account.
+ audience (str):
+ Audience to be used when generating OIDC
+ token. The audience claim identifies the
+ recipients that the JWT is intended for. The
+ audience value is a single case-sensitive
+ string. Having multiple values (array) for the
+ audience field is not supported. More info about
+ the OIDC JWT token audience here:
+ https://tools.ietf.org/html/rfc7519#section-4.1.3
+ Note: if not specified, the Push endpoint URL
+ will be used.
+ """
+
+ service_account_email = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ audience = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+
+ push_endpoint = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ attributes = proto.MapField(
+ proto.STRING,
+ proto.STRING,
+ number=2,
+ )
+ oidc_token = proto.Field(
+ proto.MESSAGE,
+ number=3,
+ oneof="authentication_method",
+ message=OidcToken,
+ )
+
+
+class BigQueryConfig(proto.Message):
+ r"""Configuration for a BigQuery subscription.
+
+ Attributes:
+ table (str):
+ The name of the table to which to write data,
+ of the form {projectId}:{datasetId}.{tableId}
+ use_topic_schema (bool):
+ When true, use the topic's schema as the
+ columns to write to in BigQuery, if it exists.
+ write_metadata (bool):
+ When true, write the subscription name, message_id,
+ publish_time, attributes, and ordering_key to additional
+ columns in the table. The subscription name, message_id, and
+ publish_time fields are put in their own columns while all
+ other message properties (other than data) are written to a
+ JSON object in the attributes column.
+ drop_unknown_fields (bool):
+ When true and use_topic_schema is true, any fields that are
+ a part of the topic schema that are not part of the BigQuery
+ table schema are dropped when writing to BigQuery.
+ Otherwise, the schemas must be kept in sync and any messages
+ with extra fields are not written and remain in the
+ subscription's backlog.
+ state (google.pubsub_v1.types.BigQueryConfig.State):
+ Output only. An output-only field that
+ indicates whether or not the subscription can
+ receive messages.
+ """
+
+ class State(proto.Enum):
+ r"""Possible states for a BigQuery subscription."""
+ STATE_UNSPECIFIED = 0
+ ACTIVE = 1
+ PERMISSION_DENIED = 2
+ NOT_FOUND = 3
+ SCHEMA_MISMATCH = 4
+
+ table = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ use_topic_schema = proto.Field(
+ proto.BOOL,
+ number=2,
+ )
+ write_metadata = proto.Field(
+ proto.BOOL,
+ number=3,
+ )
+ drop_unknown_fields = proto.Field(
+ proto.BOOL,
+ number=4,
+ )
+ state = proto.Field(
+ proto.ENUM,
+ number=5,
+ enum=State,
+ )
+
+
+class ReceivedMessage(proto.Message):
+ r"""A message and its corresponding acknowledgment ID.
+
+ Attributes:
+ ack_id (str):
+ This ID can be used to acknowledge the
+ received message.
+ message (google.pubsub_v1.types.PubsubMessage):
+ The message.
+ delivery_attempt (int):
+ The approximate number of times that Cloud Pub/Sub has
+ attempted to deliver the associated message to a subscriber.
+
+ More precisely, this is 1 + (number of NACKs) + (number of
+ ack_deadline exceeds) for this message.
+
+ A NACK is any call to ModifyAckDeadline with a 0 deadline.
+ An ack_deadline exceeds event is whenever a message is not
+ acknowledged within ack_deadline. Note that ack_deadline is
+ initially Subscription.ackDeadlineSeconds, but may get
+ extended automatically by the client library.
+
+ Upon the first delivery of a given message,
+ ``delivery_attempt`` will have a value of 1. The value is
+ calculated at best effort and is approximate.
+
+ If a DeadLetterPolicy is not set on the subscription, this
+ will be 0.
+ """
+
+ ack_id = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ message = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message="PubsubMessage",
+ )
+ delivery_attempt = proto.Field(
+ proto.INT32,
+ number=3,
+ )
+
+
+class GetSubscriptionRequest(proto.Message):
+ r"""Request for the GetSubscription method.
+
+ Attributes:
+ subscription (str):
+ Required. The name of the subscription to get. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class UpdateSubscriptionRequest(proto.Message):
+ r"""Request for the UpdateSubscription method.
+
+ Attributes:
+ subscription (google.pubsub_v1.types.Subscription):
+ Required. The updated subscription object.
+ update_mask (google.protobuf.field_mask_pb2.FieldMask):
+ Required. Indicates which fields in the
+ provided subscription to update. Must be
+ specified and non-empty.
+ """
+
+ subscription = proto.Field(
+ proto.MESSAGE,
+ number=1,
+ message="Subscription",
+ )
+ update_mask = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message=field_mask_pb2.FieldMask,
+ )
+
+
+class ListSubscriptionsRequest(proto.Message):
+ r"""Request for the ``ListSubscriptions`` method.
+
+ Attributes:
+ project (str):
+ Required. The name of the project in which to list
+ subscriptions. Format is ``projects/{project-id}``.
+ page_size (int):
+ Maximum number of subscriptions to return.
+ page_token (str):
+ The value returned by the last
+ ``ListSubscriptionsResponse``; indicates that this is a
+ continuation of a prior ``ListSubscriptions`` call, and that
+ the system should return the next page of data.
+ """
+
+ project = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ page_size = proto.Field(
+ proto.INT32,
+ number=2,
+ )
+ page_token = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+
+
+class ListSubscriptionsResponse(proto.Message):
+ r"""Response for the ``ListSubscriptions`` method.
+
+ Attributes:
+ subscriptions (Sequence[google.pubsub_v1.types.Subscription]):
+ The subscriptions that match the request.
+ next_page_token (str):
+ If not empty, indicates that there may be more subscriptions
+ that match the request; this value should be passed in a new
+ ``ListSubscriptionsRequest`` to get more subscriptions.
+ """
+
+ @property
+ def raw_page(self):
+ return self
+
+ subscriptions = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="Subscription",
+ )
+ next_page_token = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+
+
+class DeleteSubscriptionRequest(proto.Message):
+ r"""Request for the DeleteSubscription method.
+
+ Attributes:
+ subscription (str):
+ Required. The subscription to delete. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class ModifyPushConfigRequest(proto.Message):
+ r"""Request for the ModifyPushConfig method.
+
+ Attributes:
+ subscription (str):
+ Required. The name of the subscription. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ push_config (google.pubsub_v1.types.PushConfig):
+ Required. The push configuration for future deliveries.
+
+ An empty ``pushConfig`` indicates that the Pub/Sub system
+ should stop pushing messages from the given subscription and
+ allow messages to be pulled and acknowledged - effectively
+ pausing the subscription if ``Pull`` or ``StreamingPull`` is
+ not called.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ push_config = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message="PushConfig",
+ )
+
+
+class PullRequest(proto.Message):
+ r"""Request for the ``Pull`` method.
+
+ Attributes:
+ subscription (str):
+ Required. The subscription from which messages should be
+ pulled. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ return_immediately (bool):
+ Optional. If this field set to true, the system will respond
+ immediately even if it there are no messages available to
+ return in the ``Pull`` response. Otherwise, the system may
+ wait (for a bounded amount of time) until at least one
+ message is available, rather than returning no messages.
+ Warning: setting this field to ``true`` is discouraged
+ because it adversely impacts the performance of ``Pull``
+ operations. We recommend that users do not set this field.
+ max_messages (int):
+ Required. The maximum number of messages to
+ return for this request. Must be a positive
+ integer. The Pub/Sub system may return fewer
+ than the number specified.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ return_immediately = proto.Field(
+ proto.BOOL,
+ number=2,
+ )
+ max_messages = proto.Field(
+ proto.INT32,
+ number=3,
+ )
+
+
+class PullResponse(proto.Message):
+ r"""Response for the ``Pull`` method.
+
+ Attributes:
+ received_messages (Sequence[google.pubsub_v1.types.ReceivedMessage]):
+ Received Pub/Sub messages. The list will be empty if there
+ are no more messages available in the backlog. For JSON, the
+ response can be entirely empty. The Pub/Sub system may
+ return fewer than the ``maxMessages`` requested even if
+ there are more messages available in the backlog.
+ """
+
+ received_messages = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="ReceivedMessage",
+ )
+
+
+class ModifyAckDeadlineRequest(proto.Message):
+ r"""Request for the ModifyAckDeadline method.
+
+ Attributes:
+ subscription (str):
+ Required. The name of the subscription. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ ack_ids (Sequence[str]):
+ Required. List of acknowledgment IDs.
+ ack_deadline_seconds (int):
+ Required. The new ack deadline with respect to the time this
+ request was sent to the Pub/Sub system. For example, if the
+ value is 10, the new ack deadline will expire 10 seconds
+ after the ``ModifyAckDeadline`` call was made. Specifying
+ zero might immediately make the message available for
+ delivery to another subscriber client. This typically
+ results in an increase in the rate of message redeliveries
+ (that is, duplicates). The minimum deadline you can specify
+ is 0 seconds. The maximum deadline you can specify is 600
+ seconds (10 minutes).
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=4,
+ )
+ ack_deadline_seconds = proto.Field(
+ proto.INT32,
+ number=3,
+ )
+
+
+class AcknowledgeRequest(proto.Message):
+ r"""Request for the Acknowledge method.
+
+ Attributes:
+ subscription (str):
+ Required. The subscription whose message is being
+ acknowledged. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ ack_ids (Sequence[str]):
+ Required. The acknowledgment ID for the messages being
+ acknowledged that was returned by the Pub/Sub system in the
+ ``Pull`` response. Must not be empty.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=2,
+ )
+
+
+class StreamingPullRequest(proto.Message):
+ r"""Request for the ``StreamingPull`` streaming RPC method. This request
+ is used to establish the initial stream as well as to stream
+ acknowledgements and ack deadline modifications from the client to
+ the server.
+
+ Attributes:
+ subscription (str):
+ Required. The subscription for which to initialize the new
+ stream. This must be provided in the first request on the
+ stream, and must not be set in subsequent requests from
+ client to server. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ ack_ids (Sequence[str]):
+ List of acknowledgement IDs for acknowledging previously
+ received messages (received on this stream or a different
+ stream). If an ack ID has expired, the corresponding message
+ may be redelivered later. Acknowledging a message more than
+ once will not result in an error. If the acknowledgement ID
+ is malformed, the stream will be aborted with status
+ ``INVALID_ARGUMENT``.
+ modify_deadline_seconds (Sequence[int]):
+ The list of new ack deadlines for the IDs listed in
+ ``modify_deadline_ack_ids``. The size of this list must be
+ the same as the size of ``modify_deadline_ack_ids``. If it
+ differs the stream will be aborted with
+ ``INVALID_ARGUMENT``. Each element in this list is applied
+ to the element in the same position in
+ ``modify_deadline_ack_ids``. The new ack deadline is with
+ respect to the time this request was sent to the Pub/Sub
+ system. Must be >= 0. For example, if the value is 10, the
+ new ack deadline will expire 10 seconds after this request
+ is received. If the value is 0, the message is immediately
+ made available for another streaming or non-streaming pull
+ request. If the value is < 0 (an error), the stream will be
+ aborted with status ``INVALID_ARGUMENT``.
+ modify_deadline_ack_ids (Sequence[str]):
+ List of acknowledgement IDs whose deadline will be modified
+ based on the corresponding element in
+ ``modify_deadline_seconds``. This field can be used to
+ indicate that more time is needed to process a message by
+ the subscriber, or to make the message available for
+ redelivery if the processing was interrupted.
+ stream_ack_deadline_seconds (int):
+ Required. The ack deadline to use for the
+ stream. This must be provided in the first
+ request on the stream, but it can also be
+ updated on subsequent requests from client to
+ server. The minimum deadline you can specify is
+ 10 seconds. The maximum deadline you can specify
+ is 600 seconds (10 minutes).
+ client_id (str):
+ A unique identifier that is used to distinguish client
+ instances from each other. Only needs to be provided on the
+ initial request. When a stream disconnects and reconnects
+ for the same stream, the client_id should be set to the same
+ value so that state associated with the old stream can be
+ transferred to the new stream. The same client_id should not
+ be used for different client instances.
+ max_outstanding_messages (int):
+ Flow control settings for the maximum number of outstanding
+ messages. When there are ``max_outstanding_messages`` or
+ more currently sent to the streaming pull client that have
+ not yet been acked or nacked, the server stops sending more
+ messages. The sending of messages resumes once the number of
+ outstanding messages is less than this value. If the value
+ is <= 0, there is no limit to the number of outstanding
+ messages. This property can only be set on the initial
+ StreamingPullRequest. If it is set on a subsequent request,
+ the stream will be aborted with status ``INVALID_ARGUMENT``.
+ max_outstanding_bytes (int):
+ Flow control settings for the maximum number of outstanding
+ bytes. When there are ``max_outstanding_bytes`` or more
+ worth of messages currently sent to the streaming pull
+ client that have not yet been acked or nacked, the server
+ will stop sending more messages. The sending of messages
+ resumes once the number of outstanding bytes is less than
+ this value. If the value is <= 0, there is no limit to the
+ number of outstanding bytes. This property can only be set
+ on the initial StreamingPullRequest. If it is set on a
+ subsequent request, the stream will be aborted with status
+ ``INVALID_ARGUMENT``.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=2,
+ )
+ modify_deadline_seconds = proto.RepeatedField(
+ proto.INT32,
+ number=3,
+ )
+ modify_deadline_ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=4,
+ )
+ stream_ack_deadline_seconds = proto.Field(
+ proto.INT32,
+ number=5,
+ )
+ client_id = proto.Field(
+ proto.STRING,
+ number=6,
+ )
+ max_outstanding_messages = proto.Field(
+ proto.INT64,
+ number=7,
+ )
+ max_outstanding_bytes = proto.Field(
+ proto.INT64,
+ number=8,
+ )
+
+
+class StreamingPullResponse(proto.Message):
+ r"""Response for the ``StreamingPull`` method. This response is used to
+ stream messages from the server to the client.
+
+ Attributes:
+ received_messages (Sequence[google.pubsub_v1.types.ReceivedMessage]):
+ Received Pub/Sub messages. This will not be
+ empty.
+ acknowledge_confirmation (google.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation):
+ This field will only be set if
+ ``enable_exactly_once_delivery`` is set to ``true``.
+ modify_ack_deadline_confirmation (google.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation):
+ This field will only be set if
+ ``enable_exactly_once_delivery`` is set to ``true``.
+ subscription_properties (google.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties):
+ Properties associated with this subscription.
+ """
+
+ class AcknowledgeConfirmation(proto.Message):
+ r"""Acknowledgement IDs sent in one or more previous requests to
+ acknowledge a previously received message.
+
+ Attributes:
+ ack_ids (Sequence[str]):
+ Successfully processed acknowledgement IDs.
+ invalid_ack_ids (Sequence[str]):
+ List of acknowledgement IDs that were
+ malformed or whose acknowledgement deadline has
+ expired.
+ unordered_ack_ids (Sequence[str]):
+ List of acknowledgement IDs that were out of
+ order.
+ """
+
+ ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+ invalid_ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=2,
+ )
+ unordered_ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=3,
+ )
+
+ class ModifyAckDeadlineConfirmation(proto.Message):
+ r"""Acknowledgement IDs sent in one or more previous requests to
+ modify the deadline for a specific message.
+
+ Attributes:
+ ack_ids (Sequence[str]):
+ Successfully processed acknowledgement IDs.
+ invalid_ack_ids (Sequence[str]):
+ List of acknowledgement IDs that were
+ malformed or whose acknowledgement deadline has
+ expired.
+ """
+
+ ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=1,
+ )
+ invalid_ack_ids = proto.RepeatedField(
+ proto.STRING,
+ number=2,
+ )
+
+ class SubscriptionProperties(proto.Message):
+ r"""Subscription properties sent as part of the response.
+
+ Attributes:
+ exactly_once_delivery_enabled (bool):
+ True iff exactly once delivery is enabled for
+ this subscription.
+ message_ordering_enabled (bool):
+ True iff message ordering is enabled for this
+ subscription.
+ """
+
+ exactly_once_delivery_enabled = proto.Field(
+ proto.BOOL,
+ number=1,
+ )
+ message_ordering_enabled = proto.Field(
+ proto.BOOL,
+ number=2,
+ )
+
+ received_messages = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="ReceivedMessage",
+ )
+ acknowledge_confirmation = proto.Field(
+ proto.MESSAGE,
+ number=5,
+ message=AcknowledgeConfirmation,
+ )
+ modify_ack_deadline_confirmation = proto.Field(
+ proto.MESSAGE,
+ number=3,
+ message=ModifyAckDeadlineConfirmation,
+ )
+ subscription_properties = proto.Field(
+ proto.MESSAGE,
+ number=4,
+ message=SubscriptionProperties,
+ )
+
+
+class CreateSnapshotRequest(proto.Message):
+ r"""Request for the ``CreateSnapshot`` method.
+
+ Attributes:
+ name (str):
+ Required. User-provided name for this snapshot. If the name
+ is not provided in the request, the server will assign a
+ random name for this snapshot on the same project as the
+ subscription. Note that for REST API requests, you must
+ specify a name. See the resource name rules. Format is
+ ``projects/{project}/snapshots/{snap}``.
+ subscription (str):
+ Required. The subscription whose backlog the snapshot
+ retains. Specifically, the created snapshot is guaranteed to
+ retain: (a) The existing backlog on the subscription. More
+ precisely, this is defined as the messages in the
+ subscription's backlog that are unacknowledged upon the
+ successful completion of the ``CreateSnapshot`` request; as
+ well as: (b) Any messages published to the subscription's
+ topic following the successful completion of the
+ CreateSnapshot request. Format is
+ ``projects/{project}/subscriptions/{sub}``.
+ labels (Mapping[str, str]):
+ See
+ Creating and managing labels .
+ """
+
+ name = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ subscription = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+ labels = proto.MapField(
+ proto.STRING,
+ proto.STRING,
+ number=3,
+ )
+
+
+class UpdateSnapshotRequest(proto.Message):
+ r"""Request for the UpdateSnapshot method.
+
+ Attributes:
+ snapshot (google.pubsub_v1.types.Snapshot):
+ Required. The updated snapshot object.
+ update_mask (google.protobuf.field_mask_pb2.FieldMask):
+ Required. Indicates which fields in the
+ provided snapshot to update. Must be specified
+ and non-empty.
+ """
+
+ snapshot = proto.Field(
+ proto.MESSAGE,
+ number=1,
+ message="Snapshot",
+ )
+ update_mask = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message=field_mask_pb2.FieldMask,
+ )
+
+
+class Snapshot(proto.Message):
+ r"""A snapshot resource. Snapshots are used in
+ `Seek `__
+ operations, which allow you to manage message acknowledgments in
+ bulk. That is, you can set the acknowledgment state of messages in
+ an existing subscription to the state captured by a snapshot.
+
+ Attributes:
+ name (str):
+ The name of the snapshot.
+ topic (str):
+ The name of the topic from which this
+ snapshot is retaining messages.
+ expire_time (google.protobuf.timestamp_pb2.Timestamp):
+ The snapshot is guaranteed to exist up until this time. A
+ newly-created snapshot expires no later than 7 days from the
+ time of its creation. Its exact lifetime is determined at
+ creation by the existing backlog in the source subscription.
+ Specifically, the lifetime of the snapshot is
+ ``7 days - (age of oldest unacked message in the subscription)``.
+ For example, consider a subscription whose oldest unacked
+ message is 3 days old. If a snapshot is created from this
+ subscription, the snapshot -- which will always capture this
+ 3-day-old backlog as long as the snapshot exists -- will
+ expire in 4 days. The service will refuse to create a
+ snapshot that would expire in less than 1 hour after
+ creation.
+ labels (Mapping[str, str]):
+ See [Creating and managing labels]
+ (https://cloud.google.com/pubsub/docs/labels).
+ """
+
+ name = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ topic = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+ expire_time = proto.Field(
+ proto.MESSAGE,
+ number=3,
+ message=timestamp_pb2.Timestamp,
+ )
+ labels = proto.MapField(
+ proto.STRING,
+ proto.STRING,
+ number=4,
+ )
+
+
+class GetSnapshotRequest(proto.Message):
+ r"""Request for the GetSnapshot method.
+
+ Attributes:
+ snapshot (str):
+ Required. The name of the snapshot to get. Format is
+ ``projects/{project}/snapshots/{snap}``.
+ """
+
+ snapshot = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class ListSnapshotsRequest(proto.Message):
+ r"""Request for the ``ListSnapshots`` method.
+
+ Attributes:
+ project (str):
+ Required. The name of the project in which to list
+ snapshots. Format is ``projects/{project-id}``.
+ page_size (int):
+ Maximum number of snapshots to return.
+ page_token (str):
+ The value returned by the last ``ListSnapshotsResponse``;
+ indicates that this is a continuation of a prior
+ ``ListSnapshots`` call, and that the system should return
+ the next page of data.
+ """
+
+ project = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ page_size = proto.Field(
+ proto.INT32,
+ number=2,
+ )
+ page_token = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+
+
+class ListSnapshotsResponse(proto.Message):
+ r"""Response for the ``ListSnapshots`` method.
+
+ Attributes:
+ snapshots (Sequence[google.pubsub_v1.types.Snapshot]):
+ The resulting snapshots.
+ next_page_token (str):
+ If not empty, indicates that there may be more snapshot that
+ match the request; this value should be passed in a new
+ ``ListSnapshotsRequest``.
+ """
+
+ @property
+ def raw_page(self):
+ return self
+
+ snapshots = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="Snapshot",
+ )
+ next_page_token = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+
+
+class DeleteSnapshotRequest(proto.Message):
+ r"""Request for the ``DeleteSnapshot`` method.
+
+ Attributes:
+ snapshot (str):
+ Required. The name of the snapshot to delete. Format is
+ ``projects/{project}/snapshots/{snap}``.
+ """
+
+ snapshot = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class SeekRequest(proto.Message):
+ r"""Request for the ``Seek`` method.
+
+ 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:
+ subscription (str):
+ Required. The subscription to affect.
+ time (google.protobuf.timestamp_pb2.Timestamp):
+ The time to seek to. Messages retained in the subscription
+ that were published before this time are marked as
+ acknowledged, and messages retained in the subscription that
+ were published after this time are marked as unacknowledged.
+ Note that this operation affects only those messages
+ retained in the subscription (configured by the combination
+ of ``message_retention_duration`` and
+ ``retain_acked_messages``). For example, if ``time``
+ corresponds to a point before the message retention window
+ (or to a point before the system's notion of the
+ subscription creation time), only retained messages will be
+ marked as unacknowledged, and already-expunged messages will
+ not be restored.
+
+ This field is a member of `oneof`_ ``target``.
+ snapshot (str):
+ The snapshot to seek to. The snapshot's topic must be the
+ same as that of the provided subscription. Format is
+ ``projects/{project}/snapshots/{snap}``.
+
+ This field is a member of `oneof`_ ``target``.
+ """
+
+ subscription = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ time = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ oneof="target",
+ message=timestamp_pb2.Timestamp,
+ )
+ snapshot = proto.Field(
+ proto.STRING,
+ number=3,
+ oneof="target",
+ )
+
+
+class SeekResponse(proto.Message):
+ r"""Response for the ``Seek`` method (this response is empty)."""
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/schema.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/schema.py
new file mode 100644
index 000000000000..59fe3aa3e5b8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/google/pubsub_v1/types/schema.py
@@ -0,0 +1,318 @@
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import proto # type: ignore
+
+
+__protobuf__ = proto.module(
+ package="google.pubsub.v1",
+ manifest={
+ "SchemaView",
+ "Encoding",
+ "Schema",
+ "CreateSchemaRequest",
+ "GetSchemaRequest",
+ "ListSchemasRequest",
+ "ListSchemasResponse",
+ "DeleteSchemaRequest",
+ "ValidateSchemaRequest",
+ "ValidateSchemaResponse",
+ "ValidateMessageRequest",
+ "ValidateMessageResponse",
+ },
+)
+
+
+class SchemaView(proto.Enum):
+ r"""View of Schema object fields to be returned by GetSchema and
+ ListSchemas.
+ """
+ SCHEMA_VIEW_UNSPECIFIED = 0
+ BASIC = 1
+ FULL = 2
+
+
+class Encoding(proto.Enum):
+ r"""Possible encoding types for messages."""
+ ENCODING_UNSPECIFIED = 0
+ JSON = 1
+ BINARY = 2
+
+
+class Schema(proto.Message):
+ r"""A schema resource.
+
+ Attributes:
+ name (str):
+ Required. Name of the schema. Format is
+ ``projects/{project}/schemas/{schema}``.
+ type_ (google.pubsub_v1.types.Schema.Type):
+ The type of the schema definition.
+ definition (str):
+ The definition of the schema. This should contain a string
+ representing the full definition of the schema that is a
+ valid schema definition of the type specified in ``type``.
+ """
+
+ class Type(proto.Enum):
+ r"""Possible schema definition types."""
+ TYPE_UNSPECIFIED = 0
+ PROTOCOL_BUFFER = 1
+ AVRO = 2
+
+ name = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ type_ = proto.Field(
+ proto.ENUM,
+ number=2,
+ enum=Type,
+ )
+ definition = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+
+
+class CreateSchemaRequest(proto.Message):
+ r"""Request for the CreateSchema method.
+
+ Attributes:
+ parent (str):
+ Required. The name of the project in which to create the
+ schema. Format is ``projects/{project-id}``.
+ schema (google.pubsub_v1.types.Schema):
+ Required. The schema object to create.
+
+ This schema's ``name`` parameter is ignored. The schema
+ object returned by CreateSchema will have a ``name`` made
+ using the given ``parent`` and ``schema_id``.
+ schema_id (str):
+ The ID to use for the schema, which will become the final
+ component of the schema's resource name.
+
+ See
+ https://cloud.google.com/pubsub/docs/admin#resource_names
+ for resource name constraints.
+ """
+
+ parent = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ schema = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message="Schema",
+ )
+ schema_id = proto.Field(
+ proto.STRING,
+ number=3,
+ )
+
+
+class GetSchemaRequest(proto.Message):
+ r"""Request for the GetSchema method.
+
+ Attributes:
+ name (str):
+ Required. The name of the schema to get. Format is
+ ``projects/{project}/schemas/{schema}``.
+ view (google.pubsub_v1.types.SchemaView):
+ The set of fields to return in the response. If not set,
+ returns a Schema with ``name`` and ``type``, but not
+ ``definition``. Set to ``FULL`` to retrieve all fields.
+ """
+
+ name = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ view = proto.Field(
+ proto.ENUM,
+ number=2,
+ enum="SchemaView",
+ )
+
+
+class ListSchemasRequest(proto.Message):
+ r"""Request for the ``ListSchemas`` method.
+
+ Attributes:
+ parent (str):
+ Required. The name of the project in which to list schemas.
+ Format is ``projects/{project-id}``.
+ view (google.pubsub_v1.types.SchemaView):
+ The set of Schema fields to return in the response. If not
+ set, returns Schemas with ``name`` and ``type``, but not
+ ``definition``. Set to ``FULL`` to retrieve all fields.
+ page_size (int):
+ Maximum number of schemas to return.
+ page_token (str):
+ The value returned by the last ``ListSchemasResponse``;
+ indicates that this is a continuation of a prior
+ ``ListSchemas`` call, and that the system should return the
+ next page of data.
+ """
+
+ parent = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ view = proto.Field(
+ proto.ENUM,
+ number=2,
+ enum="SchemaView",
+ )
+ page_size = proto.Field(
+ proto.INT32,
+ number=3,
+ )
+ page_token = proto.Field(
+ proto.STRING,
+ number=4,
+ )
+
+
+class ListSchemasResponse(proto.Message):
+ r"""Response for the ``ListSchemas`` method.
+
+ Attributes:
+ schemas (Sequence[google.pubsub_v1.types.Schema]):
+ The resulting schemas.
+ next_page_token (str):
+ If not empty, indicates that there may be more schemas that
+ match the request; this value should be passed in a new
+ ``ListSchemasRequest``.
+ """
+
+ @property
+ def raw_page(self):
+ return self
+
+ schemas = proto.RepeatedField(
+ proto.MESSAGE,
+ number=1,
+ message="Schema",
+ )
+ next_page_token = proto.Field(
+ proto.STRING,
+ number=2,
+ )
+
+
+class DeleteSchemaRequest(proto.Message):
+ r"""Request for the ``DeleteSchema`` method.
+
+ Attributes:
+ name (str):
+ Required. Name of the schema to delete. Format is
+ ``projects/{project}/schemas/{schema}``.
+ """
+
+ name = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+
+
+class ValidateSchemaRequest(proto.Message):
+ r"""Request for the ``ValidateSchema`` method.
+
+ Attributes:
+ parent (str):
+ Required. The name of the project in which to validate
+ schemas. Format is ``projects/{project-id}``.
+ schema (google.pubsub_v1.types.Schema):
+ Required. The schema object to validate.
+ """
+
+ parent = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ schema = proto.Field(
+ proto.MESSAGE,
+ number=2,
+ message="Schema",
+ )
+
+
+class ValidateSchemaResponse(proto.Message):
+ r"""Response for the ``ValidateSchema`` method. Empty for now."""
+
+
+class ValidateMessageRequest(proto.Message):
+ r"""Request for the ``ValidateMessage`` method.
+
+ 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:
+ parent (str):
+ Required. The name of the project in which to validate
+ schemas. Format is ``projects/{project-id}``.
+ name (str):
+ Name of the schema against which to validate.
+
+ Format is ``projects/{project}/schemas/{schema}``.
+
+ This field is a member of `oneof`_ ``schema_spec``.
+ schema (google.pubsub_v1.types.Schema):
+ Ad-hoc schema against which to validate
+
+ This field is a member of `oneof`_ ``schema_spec``.
+ message (bytes):
+ Message to validate against the provided ``schema_spec``.
+ encoding (google.pubsub_v1.types.Encoding):
+ The encoding expected for messages
+ """
+
+ parent = proto.Field(
+ proto.STRING,
+ number=1,
+ )
+ name = proto.Field(
+ proto.STRING,
+ number=2,
+ oneof="schema_spec",
+ )
+ schema = proto.Field(
+ proto.MESSAGE,
+ number=3,
+ oneof="schema_spec",
+ message="Schema",
+ )
+ message = proto.Field(
+ proto.BYTES,
+ number=4,
+ )
+ encoding = proto.Field(
+ proto.ENUM,
+ number=5,
+ enum="Encoding",
+ )
+
+
+class ValidateMessageResponse(proto.Message):
+ r"""Response for the ``ValidateMessage`` method. Empty for now."""
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/decrypt-secrets.sh b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/decrypt-secrets.sh
new file mode 100755
index 000000000000..21f6d2a26d90
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/decrypt-secrets.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+ROOT=$( dirname "$DIR" )
+
+# Work from the project root.
+cd $ROOT
+
+# Prevent it from overriding files.
+# We recommend that sample authors use their own service account files and cloud project.
+# In that case, they are supposed to prepare these files by themselves.
+if [[ -f "testing/test-env.sh" ]] || \
+ [[ -f "testing/service-account.json" ]] || \
+ [[ -f "testing/client-secrets.json" ]]; then
+ echo "One or more target files exist, aborting."
+ exit 1
+fi
+
+# Use SECRET_MANAGER_PROJECT if set, fallback to cloud-devrel-kokoro-resources.
+PROJECT_ID="${SECRET_MANAGER_PROJECT:-cloud-devrel-kokoro-resources}"
+
+gcloud secrets versions access latest --secret="python-docs-samples-test-env" \
+ --project="${PROJECT_ID}" \
+ > testing/test-env.sh
+gcloud secrets versions access latest \
+ --secret="python-docs-samples-service-account" \
+ --project="${PROJECT_ID}" \
+ > testing/service-account.json
+gcloud secrets versions access latest \
+ --secret="python-docs-samples-client-secrets" \
+ --project="${PROJECT_ID}" \
+ > testing/client-secrets.json
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/fixup_pubsub_v1_keywords.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/fixup_pubsub_v1_keywords.py
new file mode 100644
index 000000000000..d1bbcedf98af
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/fixup_pubsub_v1_keywords.py
@@ -0,0 +1,209 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import argparse
+import os
+import libcst as cst
+import pathlib
+import sys
+from typing import (Any, Callable, Dict, List, Sequence, Tuple)
+
+
+def partition(
+ predicate: Callable[[Any], bool],
+ iterator: Sequence[Any]
+) -> Tuple[List[Any], List[Any]]:
+ """A stable, out-of-place partition."""
+ results = ([], [])
+
+ for i in iterator:
+ results[int(predicate(i))].append(i)
+
+ # Returns trueList, falseList
+ return results[1], results[0]
+
+
+class pubsubCallTransformer(cst.CSTTransformer):
+ CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata')
+ METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
+ 'acknowledge': ('subscription', 'ack_ids', ),
+ 'create_schema': ('parent', 'schema', 'schema_id', ),
+ 'create_snapshot': ('name', 'subscription', 'labels', ),
+ 'create_subscription': ('name', 'topic', 'push_config', 'bigquery_config', 'ack_deadline_seconds', 'retain_acked_messages', 'message_retention_duration', 'labels', 'enable_message_ordering', 'expiration_policy', 'filter', 'dead_letter_policy', 'retry_policy', 'detached', 'enable_exactly_once_delivery', 'topic_message_retention_duration', 'state', ),
+ 'create_topic': ('name', 'labels', 'message_storage_policy', 'kms_key_name', 'schema_settings', 'satisfies_pzs', 'message_retention_duration', ),
+ 'delete_schema': ('name', ),
+ 'delete_snapshot': ('snapshot', ),
+ 'delete_subscription': ('subscription', ),
+ 'delete_topic': ('topic', ),
+ 'detach_subscription': ('subscription', ),
+ 'get_schema': ('name', 'view', ),
+ 'get_snapshot': ('snapshot', ),
+ 'get_subscription': ('subscription', ),
+ 'get_topic': ('topic', ),
+ 'list_schemas': ('parent', 'view', 'page_size', 'page_token', ),
+ 'list_snapshots': ('project', 'page_size', 'page_token', ),
+ 'list_subscriptions': ('project', 'page_size', 'page_token', ),
+ 'list_topics': ('project', 'page_size', 'page_token', ),
+ 'list_topic_snapshots': ('topic', 'page_size', 'page_token', ),
+ 'list_topic_subscriptions': ('topic', 'page_size', 'page_token', ),
+ 'modify_ack_deadline': ('subscription', 'ack_ids', 'ack_deadline_seconds', ),
+ 'modify_push_config': ('subscription', 'push_config', ),
+ 'publish': ('topic', 'messages', ),
+ 'pull': ('subscription', 'max_messages', 'return_immediately', ),
+ 'seek': ('subscription', 'time', 'snapshot', ),
+ 'streaming_pull': ('subscription', 'stream_ack_deadline_seconds', 'ack_ids', 'modify_deadline_seconds', 'modify_deadline_ack_ids', 'client_id', 'max_outstanding_messages', 'max_outstanding_bytes', ),
+ 'update_snapshot': ('snapshot', 'update_mask', ),
+ 'update_subscription': ('subscription', 'update_mask', ),
+ 'update_topic': ('topic', 'update_mask', ),
+ 'validate_message': ('parent', 'name', 'schema', 'message', 'encoding', ),
+ 'validate_schema': ('parent', 'schema', ),
+ 'get_iam_policy': ('resource', 'options', ),
+ 'set_iam_policy': ('resource', 'policy', ),
+ 'test_iam_permissions': ('resource', 'permissions', ),
+ }
+
+ def leave_Call(self, original: cst.Call, updated: cst.Call) -> cst.CSTNode:
+ try:
+ key = original.func.attr.value
+ kword_params = self.METHOD_TO_PARAMS[key]
+ except (AttributeError, KeyError):
+ # Either not a method from the API or too convoluted to be sure.
+ return updated
+
+ # If the existing code is valid, keyword args come after positional args.
+ # Therefore, all positional args must map to the first parameters.
+ args, kwargs = partition(lambda a: not bool(a.keyword), updated.args)
+ if any(k.keyword.value == "request" for k in kwargs):
+ # We've already fixed this file, don't fix it again.
+ return updated
+
+ kwargs, ctrl_kwargs = partition(
+ lambda a: a.keyword.value not in self.CTRL_PARAMS,
+ kwargs
+ )
+
+ args, ctrl_args = args[:len(kword_params)], args[len(kword_params):]
+ ctrl_kwargs.extend(cst.Arg(value=a.value, keyword=cst.Name(value=ctrl))
+ for a, ctrl in zip(ctrl_args, self.CTRL_PARAMS))
+
+ request_arg = cst.Arg(
+ value=cst.Dict([
+ cst.DictElement(
+ cst.SimpleString("'{}'".format(name)),
+cst.Element(value=arg.value)
+ )
+ # Note: the args + kwargs looks silly, but keep in mind that
+ # the control parameters had to be stripped out, and that
+ # those could have been passed positionally or by keyword.
+ for name, arg in zip(kword_params, args + kwargs)]),
+ keyword=cst.Name("request")
+ )
+
+ return updated.with_changes(
+ args=[request_arg] + ctrl_kwargs
+ )
+
+
+def fix_files(
+ in_dir: pathlib.Path,
+ out_dir: pathlib.Path,
+ *,
+ transformer=pubsubCallTransformer(),
+):
+ """Duplicate the input dir to the output dir, fixing file method calls.
+
+ Preconditions:
+ * in_dir is a real directory
+ * out_dir is a real, empty directory
+ """
+ pyfile_gen = (
+ pathlib.Path(os.path.join(root, f))
+ for root, _, files in os.walk(in_dir)
+ for f in files if os.path.splitext(f)[1] == ".py"
+ )
+
+ for fpath in pyfile_gen:
+ with open(fpath, 'r') as f:
+ src = f.read()
+
+ # Parse the code and insert method call fixes.
+ tree = cst.parse_module(src)
+ updated = tree.visit(transformer)
+
+ # Create the path and directory structure for the new file.
+ updated_path = out_dir.joinpath(fpath.relative_to(in_dir))
+ updated_path.parent.mkdir(parents=True, exist_ok=True)
+
+ # Generate the updated source file at the corresponding path.
+ with open(updated_path, 'w') as f:
+ f.write(updated.code)
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description="""Fix up source that uses the pubsub client library.
+
+The existing sources are NOT overwritten but are copied to output_dir with changes made.
+
+Note: This tool operates at a best-effort level at converting positional
+ parameters in client method calls to keyword based parameters.
+ Cases where it WILL FAIL include
+ A) * or ** expansion in a method call.
+ B) Calls via function or method alias (includes free function calls)
+ C) Indirect or dispatched calls (e.g. the method is looked up dynamically)
+
+ These all constitute false negatives. The tool will also detect false
+ positives when an API method shares a name with another method.
+""")
+ parser.add_argument(
+ '-d',
+ '--input-directory',
+ required=True,
+ dest='input_dir',
+ help='the input directory to walk for python files to fix up',
+ )
+ parser.add_argument(
+ '-o',
+ '--output-directory',
+ required=True,
+ dest='output_dir',
+ help='the directory to output files fixed via un-flattening',
+ )
+ args = parser.parse_args()
+ input_dir = pathlib.Path(args.input_dir)
+ output_dir = pathlib.Path(args.output_dir)
+ if not input_dir.is_dir():
+ print(
+ f"input directory '{input_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if not output_dir.is_dir():
+ print(
+ f"output directory '{output_dir}' does not exist or is not a directory",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ if os.listdir(output_dir):
+ print(
+ f"output directory '{output_dir}' is not empty",
+ file=sys.stderr,
+ )
+ sys.exit(-1)
+
+ fix_files(input_dir, output_dir)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/readme_gen.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/readme_gen.py
new file mode 100644
index 000000000000..91b59676bfc7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/readme_gen.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+
+# Copyright 2016 Google Inc
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Generates READMEs using configuration defined in yaml."""
+
+import argparse
+import io
+import os
+import subprocess
+
+import jinja2
+import yaml
+
+
+jinja_env = jinja2.Environment(
+ trim_blocks=True,
+ loader=jinja2.FileSystemLoader(
+ os.path.abspath(os.path.join(os.path.dirname(__file__), "templates"))
+ ),
+ autoescape=True,
+)
+
+README_TMPL = jinja_env.get_template('README.tmpl.rst')
+
+
+def get_help(file):
+ return subprocess.check_output(['python', file, '--help']).decode()
+
+
+def main():
+ parser = argparse.ArgumentParser()
+ parser.add_argument('source')
+ parser.add_argument('--destination', default='README.rst')
+
+ args = parser.parse_args()
+
+ source = os.path.abspath(args.source)
+ root = os.path.dirname(source)
+ destination = os.path.join(root, args.destination)
+
+ jinja_env.globals['get_help'] = get_help
+
+ with io.open(source, 'r') as f:
+ config = yaml.load(f)
+
+ # This allows get_help to execute in the right directory.
+ os.chdir(root)
+
+ output = README_TMPL.render(config)
+
+ with io.open(destination, 'w') as f:
+ f.write(output)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/README.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/README.tmpl.rst
new file mode 100644
index 000000000000..4fd239765b0a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/README.tmpl.rst
@@ -0,0 +1,87 @@
+{# The following line is a lie. BUT! Once jinja2 is done with it, it will
+ become truth! #}
+.. This file is automatically generated. Do not edit this file directly.
+
+{{product.name}} Python Samples
+===============================================================================
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+ :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/README.rst
+
+
+This directory contains samples for {{product.name}}. {{product.description}}
+
+{{description}}
+
+.. _{{product.name}}: {{product.url}}
+
+{% if required_api_url %}
+To run the sample, you need to enable the API at: {{required_api_url}}
+{% endif %}
+
+{% if required_role %}
+To run the sample, you need to have `{{required_role}}` role.
+{% endif %}
+
+{{other_required_steps}}
+
+{% if setup %}
+Setup
+-------------------------------------------------------------------------------
+
+{% for section in setup %}
+
+{% include section + '.tmpl.rst' %}
+
+{% endfor %}
+{% endif %}
+
+{% if samples %}
+Samples
+-------------------------------------------------------------------------------
+
+{% for sample in samples %}
+{{sample.name}}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+{% if not sample.hide_cloudshell_button %}
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+ :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor={{folder}}/{{sample.file}},{{folder}}/README.rst
+{% endif %}
+
+
+{{sample.description}}
+
+To run this sample:
+
+.. code-block:: bash
+
+ $ python {{sample.file}}
+{% if sample.show_help %}
+
+ {{get_help(sample.file)|indent}}
+{% endif %}
+
+
+{% endfor %}
+{% endif %}
+
+{% if cloud_client_library %}
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source`_ and `report issues`_.
+
+.. _Google Cloud Client Library for Python:
+ https://googlecloudplatform.github.io/google-cloud-python/
+.. _browse the source:
+ https://github.com/GoogleCloudPlatform/google-cloud-python
+.. _report issues:
+ https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+{% endif %}
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/
\ No newline at end of file
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/auth.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/auth.tmpl.rst
new file mode 100644
index 000000000000..1446b94a5e3a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/auth.tmpl.rst
@@ -0,0 +1,9 @@
+Authentication
+++++++++++++++
+
+This sample requires you to have authentication setup. Refer to the
+`Authentication Getting Started Guide`_ for instructions on setting up
+credentials for applications.
+
+.. _Authentication Getting Started Guide:
+ https://cloud.google.com/docs/authentication/getting-started
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/auth_api_key.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/auth_api_key.tmpl.rst
new file mode 100644
index 000000000000..11957ce2714a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/auth_api_key.tmpl.rst
@@ -0,0 +1,14 @@
+Authentication
+++++++++++++++
+
+Authentication for this service is done via an `API Key`_. To obtain an API
+Key:
+
+1. Open the `Cloud Platform Console`_
+2. Make sure that billing is enabled for your project.
+3. From the **Credentials** page, create a new **API Key** or use an existing
+ one for your project.
+
+.. _API Key:
+ https://developers.google.com/api-client-library/python/guide/aaa_apikeys
+.. _Cloud Console: https://console.cloud.google.com/project?_
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/install_deps.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/install_deps.tmpl.rst
new file mode 100644
index 000000000000..6f069c6c87a5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/install_deps.tmpl.rst
@@ -0,0 +1,29 @@
+Install Dependencies
+++++++++++++++++++++
+
+#. Clone python-docs-samples and change directory to the sample directory you want to use.
+
+ .. code-block:: bash
+
+ $ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions.
+
+ .. _Python Development Environment Setup Guide:
+ https://cloud.google.com/python/setup
+
+#. Create a virtualenv. Samples are compatible with Python 3.7+.
+
+ .. code-block:: bash
+
+ $ virtualenv env
+ $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+ .. code-block:: bash
+
+ $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/install_portaudio.tmpl.rst b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/install_portaudio.tmpl.rst
new file mode 100644
index 000000000000..5ea33d18c00c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/scripts/readme-gen/templates/install_portaudio.tmpl.rst
@@ -0,0 +1,35 @@
+Install PortAudio
++++++++++++++++++
+
+Install `PortAudio`_. This is required by the `PyAudio`_ library to stream
+audio from your computer's microphone. PyAudio depends on PortAudio for cross-platform compatibility, and is installed differently depending on the
+platform.
+
+* For Mac OS X, you can use `Homebrew`_::
+
+ brew install portaudio
+
+ **Note**: if you encounter an error when running `pip install` that indicates
+ it can't find `portaudio.h`, try running `pip install` with the following
+ flags::
+
+ pip install --global-option='build_ext' \
+ --global-option='-I/usr/local/include' \
+ --global-option='-L/usr/local/lib' \
+ pyaudio
+
+* For Debian / Ubuntu Linux::
+
+ apt-get install portaudio19-dev python-all-dev
+
+* Windows may work without having to install PortAudio explicitly (it will get
+ installed with PyAudio).
+
+For more details, see the `PyAudio installation`_ page.
+
+
+.. _PyAudio: https://people.csail.mit.edu/hubert/pyaudio/
+.. _PortAudio: http://www.portaudio.com/
+.. _PyAudio installation:
+ https://people.csail.mit.edu/hubert/pyaudio/#downloads
+.. _Homebrew: http://brew.sh
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/setup.cfg b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/setup.cfg
new file mode 100644
index 000000000000..c3a2b39f6528
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/setup.cfg
@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Generated by synthtool. DO NOT EDIT!
+[bdist_wheel]
+universal = 1
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/setup.py b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/setup.py
new file mode 100644
index 000000000000..134b4d30e1c7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/gapic-combo/setup.py
@@ -0,0 +1,95 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import io
+import os
+
+import setuptools
+
+
+# Package metadata.
+
+name = "google-cloud-pubsub"
+description = "Google Cloud Pub/Sub API client library"
+version = "2.13.10"
+# Should be one of:
+# 'Development Status :: 3 - Alpha'
+# 'Development Status :: 4 - Beta'
+# 'Development Status :: 5 - Production/Stable'
+release_status = "Development Status :: 5 - Production/Stable"
+dependencies = [
+ "grpcio >= 1.38.1, < 2.0dev", # https://github.com/googleapis/python-pubsub/issues/414
+ "google-api-core[grpc] >= 1.32.0, <3.0.0dev,!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*",
+ "proto-plus >= 1.22.0, <2.0.0dev",
+ "protobuf>=3.19.5,<5.0.0dev,!=3.20.0,!=3.20.1,!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5",
+ "grpc-google-iam-v1 >=0.12.4, <1.0.0dev",
+ "grpcio-status >= 1.16.0",
+]
+extras = {"libcst": "libcst >= 0.3.10"}
+
+
+# Setup boilerplate below this line.
+
+package_root = os.path.abspath(os.path.dirname(__file__))
+
+readme_filename = os.path.join(package_root, "README.rst")
+with io.open(readme_filename, encoding="utf-8") as readme_file:
+ readme = readme_file.read()
+
+# Only include packages under the 'google' namespace. Do not include tests,
+# benchmarks, etc.
+packages = [
+ package
+ for package in setuptools.PEP420PackageFinder.find()
+ if package.startswith("google")
+]
+
+# Determine which namespaces are needed.
+namespaces = ["google"]
+if "google.cloud" in packages:
+ namespaces.append("google.cloud")
+
+
+setuptools.setup(
+ name=name,
+ version=version,
+ description=description,
+ long_description=readme,
+ author="Google LLC",
+ author_email="googleapis-packages@google.com",
+ license="Apache 2.0",
+ url="https://github.com/googleapis/python-pubsub",
+ classifiers=[
+ release_status,
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: Apache Software License",
+ "Programming Language :: Python",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.7",
+ "Programming Language :: Python :: 3.8",
+ "Programming Language :: Python :: 3.9",
+ "Programming Language :: Python :: 3.10",
+ "Operating System :: OS Independent",
+ "Topic :: Internet",
+ ],
+ platforms="Posix; MacOS X; Windows",
+ packages=packages,
+ namespace_packages=namespaces,
+ install_requires=dependencies,
+ extras_require=extras,
+ python_requires=">=3.7",
+ scripts=["scripts/fixup_pubsub_v1_keywords.py"],
+ include_package_data=True,
+ zip_safe=False,
+)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.Flow.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.Flow.yml
new file mode 100644
index 000000000000..cea9f1a8238f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.Flow.yml
@@ -0,0 +1,427 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google_auth_oauthlib.flow.Flow
+ - google_auth_oauthlib.flow.Flow.authorization_url
+ - google_auth_oauthlib.flow.Flow.authorized_session
+ - google_auth_oauthlib.flow.Flow.client_config
+ - google_auth_oauthlib.flow.Flow.client_type
+ - google_auth_oauthlib.flow.Flow.credentials
+ - google_auth_oauthlib.flow.Flow.fetch_token
+ - google_auth_oauthlib.flow.Flow.from_client_config
+ - google_auth_oauthlib.flow.Flow.from_client_secrets_file
+ - google_auth_oauthlib.flow.Flow.oauth2session
+ - google_auth_oauthlib.flow.Flow.redirect_uri
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: Flow
+ source:
+ id: Flow
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 74
+ summary: "OAuth 2.0 Authorization Flow\n\nThis class uses a `requests_oauthlib.OAuth2Session`\
+ \ instance at\n`oauth2session` to perform all of the OAuth 2.0 logic. This class\n\
+ just provides convenience methods and sane defaults for doing Google's\nparticular\
+ \ flavors of OAuth 2.0.\n\nTypically you'll construct an instance of this flow\
+ \ using\n`from_client_secrets_file` and a `client secrets file`_ obtained\nfrom\
+ \ the `Google API Console`_.\n\n.. _client secrets file:\n https://developers.google.com/identity/protocols/oauth2/web-server\n\
+ \ #creatingcred\n.. _Google API Console:\n https://console.developers.google.com/apis/credentials\n\
+ \n"
+ syntax:
+ content: "Flow(\n oauth2session,\n client_type,\n client_config,\n \
+ \ redirect_uri=None,\n code_verifier=None,\n autogenerate_code_verifier=True,\n\
+ )"
+ parameters: []
+ type: class
+ uid: google_auth_oauthlib.flow.Flow
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: Flow
+ source:
+ id: Flow
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 74
+ summary: ''
+ syntax:
+ content: "Flow(\n oauth2session,\n client_type,\n client_config,\n \
+ \ redirect_uri=None,\n code_verifier=None,\n autogenerate_code_verifier=True,\n\
+ )"
+ parameters:
+ - description: The OAuth 2.0 session from requests-oauthlib.
+ id: oauth2session
+ var_type: requests_oauthlib.OAuth2Session
+ - description: The client type, either web or installed.
+ id: client_type
+ var_type: str
+ - description: The client configuration in the Google client secrets_
+ format.
+ id: client_config
+ var_type: Mapping[str, Any]
+ - description: The OAuth 2.0 redirect URI if known at flow creation time. Otherwise,
+ it will need to be set using redirect_uri.
+ id: redirect_uri
+ var_type: str
+ - description: random string of 43-128 chars used to verify the key exchange.using
+ PKCE.
+ id: code_verifier
+ var_type: str
+ - description: If true, auto-generate a code_verifier.
+ id: autogenerate_code_verifier
+ var_type: 'bool .. _client secrets: https://github.com/googleapis/google-api-python-client/blob
+ /main/docs/client-secrets.md'
+ type: method
+ uid: google_auth_oauthlib.flow.Flow
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.authorization_url
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: authorization_url
+ source:
+ id: authorization_url
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 215
+ summary: 'Generates an authorization URL.
+
+
+ This is the first step in the OAuth 2.0 Authorization Flow. The user''s
+
+ browser should be redirected to the returned URL.
+
+
+ This method calls
+
+ `requests_oauthlib.OAuth2Session.authorization_url`
+
+ and specifies the client configuration''s authorization URI (usually
+
+ Google''s authorization server) and specifies that "offline" access is
+
+ desired. This is required in order to obtain a refresh token.
+
+ '
+ syntax:
+ content: authorization_url(**kwargs)
+ parameters: []
+ returns:
+ - description: The generated authorization URL and state. The user must visit
+ the URL to complete the flow. The state is used when completing the flow to
+ verify that the request originated from your application. If your application
+ is using a different Flow instance to obtain the token, you will
+ need to specify the state when constructing the Flow.
+ var_type: Tuple[str, str]
+ type: method
+ uid: google_auth_oauthlib.flow.Flow.authorization_url
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.authorized_session
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: authorized_session
+ source:
+ id: authorized_session
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 305
+ summary: 'Returns a `requests.Session` authorized with credentials.
+
+
+ `fetch_token` must be called before this method. This method
+
+ constructs a `google.auth.transport.requests.AuthorizedSession`
+
+ class using this flow''s `credentials`.
+
+ '
+ syntax:
+ content: authorized_session()
+ parameters: []
+ returns:
+ - description: The constructed session.
+ var_type: google.auth.transport.requests.AuthorizedSession
+ type: method
+ uid: google_auth_oauthlib.flow.Flow.authorized_session
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.client_config
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: client_config
+ source:
+ id: client_config
+ path: null
+ startLine: null
+ summary: 'The OAuth 2.0 client configuration.
+
+
+ :type: Mapping[str, Any]
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google_auth_oauthlib.flow.Flow.client_config
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.client_type
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: client_type
+ source:
+ id: client_type
+ path: null
+ startLine: null
+ summary: 'The client type, either `''web''` or `''installed''`
+
+
+ :type: str
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google_auth_oauthlib.flow.Flow.client_type
+- &id001
+ attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.credentials
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: credentials
+ source:
+ id: credentials
+ path: null
+ startLine: null
+ summary: 'Returns credentials from the OAuth 2.0 session.
+
+
+ `fetch_token` must be called before accessing this. This method
+
+ constructs a `google.oauth2.credentials.Credentials` class using
+
+ the session''s token and the client config.
+
+ '
+ syntax:
+ exceptions:
+ - description: If there is no access token in the session.
+ var_type: ValueError
+ returns:
+ - description: The constructed credentials.
+ var_type: google.oauth2.credentials.Credentials
+ type: property
+ uid: google_auth_oauthlib.flow.Flow.credentials
+- *id001
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.fetch_token
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: fetch_token
+ source:
+ id: fetch_token
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 260
+ summary: 'Completes the Authorization Flow and obtains an access token.
+
+
+ This is the final step in the OAuth 2.0 Authorization Flow. This is
+
+ called after the user consents.
+
+
+ This method calls
+
+ `requests_oauthlib.OAuth2Session.fetch_token`
+
+ and specifies the client configuration''s token URI (usually Google''s
+
+ token server).
+
+ '
+ syntax:
+ content: fetch_token(**kwargs)
+ parameters: []
+ returns:
+ - description: The obtained tokens. Typically, you will not use return value of
+ this function and instead use credentials to obtain a google.auth.credentials.Credentials
+ instance.
+ var_type: Mapping[str, str]
+ type: method
+ uid: google_auth_oauthlib.flow.Flow.fetch_token
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.from_client_config
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: from_client_config
+ source:
+ id: from_client_config
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 131
+ summary: 'Creates a `requests_oauthlib.OAuth2Session` from client
+
+ configuration loaded from a Google-format client secrets file.
+
+ '
+ syntax:
+ content: from_client_config(client_config, scopes, **kwargs)
+ exceptions:
+ - description: 'If the client configuration is not in the correct format. .. _client
+ secrets: https://github.com/googleapis/google-api-python-client/blob/main/docs/client-secrets.md'
+ var_type: ValueError
+ parameters:
+ - description: The client configuration in the Google client secrets_
+ format.
+ id: client_config
+ var_type: Mapping[str, Any]
+ - description: The list of scopes to request during the flow.
+ id: scopes
+ var_type: Sequence[str]
+ returns:
+ - description: The constructed Flow instance.
+ var_type: Flow
+ type: method
+ uid: google_auth_oauthlib.flow.Flow.from_client_config
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.from_client_secrets_file
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: from_client_secrets_file
+ source:
+ id: from_client_secrets_file
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 183
+ summary: 'Creates a `Flow` instance from a Google client secrets file.
+
+ '
+ syntax:
+ content: from_client_secrets_file(client_secrets_file, scopes, **kwargs)
+ parameters:
+ - description: The path to the client secrets .json file.
+ id: client_secrets_file
+ var_type: str
+ - description: The list of scopes to request during the flow.
+ id: scopes
+ var_type: Sequence[str]
+ returns:
+ - description: The constructed Flow instance.
+ var_type: Flow
+ type: method
+ uid: google_auth_oauthlib.flow.Flow.from_client_secrets_file
+- attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.oauth2session
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: oauth2session
+ source:
+ id: oauth2session
+ path: null
+ startLine: null
+ summary: 'The OAuth 2.0 session.
+
+
+ :type: requests_oauthlib.OAuth2Session
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google_auth_oauthlib.flow.Flow.oauth2session
+- &id002
+ attributes: []
+ class: google_auth_oauthlib.flow.Flow
+ fullName: google_auth_oauthlib.flow.Flow.redirect_uri
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: redirect_uri
+ source:
+ id: redirect_uri
+ path: null
+ startLine: null
+ summary: 'The OAuth 2.0 redirect URI. Pass-through to
+
+ `self.oauth2session.redirect_uri`.
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google_auth_oauthlib.flow.Flow.redirect_uri
+- *id002
+references:
+- fullName: google_auth_oauthlib.flow.Flow
+ isExternal: false
+ name: Flow
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow
+- fullName: google_auth_oauthlib.flow.Flow.authorization_url
+ isExternal: false
+ name: authorization_url
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.authorization_url
+- fullName: google_auth_oauthlib.flow.Flow.authorized_session
+ isExternal: false
+ name: authorized_session
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.authorized_session
+- fullName: google_auth_oauthlib.flow.Flow.client_config
+ isExternal: false
+ name: client_config
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.client_config
+- fullName: google_auth_oauthlib.flow.Flow.client_type
+ isExternal: false
+ name: client_type
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.client_type
+- fullName: google_auth_oauthlib.flow.Flow.credentials
+ isExternal: false
+ name: credentials
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.credentials
+- fullName: google_auth_oauthlib.flow.Flow.fetch_token
+ isExternal: false
+ name: fetch_token
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.fetch_token
+- fullName: google_auth_oauthlib.flow.Flow.from_client_config
+ isExternal: false
+ name: from_client_config
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.from_client_config
+- fullName: google_auth_oauthlib.flow.Flow.from_client_secrets_file
+ isExternal: false
+ name: from_client_secrets_file
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.from_client_secrets_file
+- fullName: google_auth_oauthlib.flow.Flow.oauth2session
+ isExternal: false
+ name: oauth2session
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.oauth2session
+- fullName: google_auth_oauthlib.flow.Flow.redirect_uri
+ isExternal: false
+ name: redirect_uri
+ parent: google_auth_oauthlib.flow.Flow
+ uid: google_auth_oauthlib.flow.Flow.redirect_uri
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.InstalledAppFlow.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.InstalledAppFlow.yml
new file mode 100644
index 000000000000..ef85206872e7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.InstalledAppFlow.yml
@@ -0,0 +1,516 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google_auth_oauthlib.flow.InstalledAppFlow
+ - google_auth_oauthlib.flow.InstalledAppFlow.authorization_url
+ - google_auth_oauthlib.flow.InstalledAppFlow.authorized_session
+ - google_auth_oauthlib.flow.InstalledAppFlow.client_config
+ - google_auth_oauthlib.flow.InstalledAppFlow.client_type
+ - google_auth_oauthlib.flow.InstalledAppFlow.credentials
+ - google_auth_oauthlib.flow.InstalledAppFlow.fetch_token
+ - google_auth_oauthlib.flow.InstalledAppFlow.from_client_config
+ - google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file
+ - google_auth_oauthlib.flow.InstalledAppFlow.oauth2session
+ - google_auth_oauthlib.flow.InstalledAppFlow.redirect_uri
+ - google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: InstalledAppFlow
+ source:
+ id: InstalledAppFlow
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 319
+ summary: "Authorization flow helper for installed applications.\n\nThis `Flow` subclass\
+ \ makes it easier to perform the\n`Installed Application Authorization Flow`_.\
+ \ This flow is useful for\nlocal development or applications that are installed\
+ \ on a desktop operating\nsystem.\n\nThis flow uses a local server strategy provided\
+ \ by `run_local_server`.\n\nExample::\n\n from google_auth_oauthlib.flow import\
+ \ InstalledAppFlow\n\n flow = InstalledAppFlow.from_client_secrets_file(\n\
+ \ 'client_secrets.json',\n scopes=['profile', 'email'])\n\n flow.run_local_server()\n\
+ \n session = flow.authorized_session()\n\n profile_info = session.get(\n\
+ \ 'https://www.googleapis.com/userinfo/v2/me').json()\n\n print(profile_info)\n\
+ \ # {'name': '...', 'email': '...', ...}\n\n\nNote that this isn't the only\
+ \ way to accomplish the installed\napplication flow, just one of the most common.\
+ \ You can use the\n`Flow` class to perform the same flow with different methods\
+ \ of\npresenting the authorization URL to the user or obtaining the authorization\n\
+ response, such as using an embedded web view.\n\n.. _Installed Application Authorization\
+ \ Flow:\n https://github.com/googleapis/google-api-python-client/blob/main/docs/oauth-installed.md\n\
+ \n"
+ syntax:
+ content: "InstalledAppFlow(\n oauth2session,\n client_type,\n client_config,\n\
+ \ redirect_uri=None,\n code_verifier=None,\n autogenerate_code_verifier=True,\n\
+ )"
+ parameters: []
+ type: class
+ uid: google_auth_oauthlib.flow.InstalledAppFlow
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: InstalledAppFlow
+ source:
+ id: InstalledAppFlow
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 319
+ summary: ''
+ syntax:
+ content: "InstalledAppFlow(\n oauth2session,\n client_type,\n client_config,\n\
+ \ redirect_uri=None,\n code_verifier=None,\n autogenerate_code_verifier=True,\n\
+ )"
+ parameters:
+ - description: The OAuth 2.0 session from requests-oauthlib.
+ id: oauth2session
+ var_type: requests_oauthlib.OAuth2Session
+ - description: The client type, either web or installed.
+ id: client_type
+ var_type: str
+ - description: The client configuration in the Google client secrets_
+ format.
+ id: client_config
+ var_type: Mapping[str, Any]
+ - description: The OAuth 2.0 redirect URI if known at flow creation time. Otherwise,
+ it will need to be set using redirect_uri.
+ id: redirect_uri
+ var_type: str
+ - description: random string of 43-128 chars used to verify the key exchange.using
+ PKCE.
+ id: code_verifier
+ var_type: str
+ - description: If true, auto-generate a code_verifier.
+ id: autogenerate_code_verifier
+ var_type: 'bool .. _client secrets: https://github.com/googleapis/google-api-python-client/blob
+ /main/docs/client-secrets.md'
+ type: method
+ uid: google_auth_oauthlib.flow.InstalledAppFlow
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.authorization_url
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: authorization_url
+ source:
+ id: authorization_url
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 215
+ summary: 'Generates an authorization URL.
+
+
+ This is the first step in the OAuth 2.0 Authorization Flow. The user''s
+
+ browser should be redirected to the returned URL.
+
+
+ This method calls
+
+ `requests_oauthlib.OAuth2Session.authorization_url`
+
+ and specifies the client configuration''s authorization URI (usually
+
+ Google''s authorization server) and specifies that "offline" access is
+
+ desired. This is required in order to obtain a refresh token.
+
+ '
+ syntax:
+ content: authorization_url(**kwargs)
+ parameters: []
+ returns:
+ - description: The generated authorization URL and state. The user must visit
+ the URL to complete the flow. The state is used when completing the flow to
+ verify that the request originated from your application. If your application
+ is using a different Flow instance to obtain the token, you will
+ need to specify the state when constructing the Flow.
+ var_type: Tuple[str, str]
+ type: method
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.authorization_url
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.authorized_session
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: authorized_session
+ source:
+ id: authorized_session
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 305
+ summary: 'Returns a `requests.Session` authorized with credentials.
+
+
+ `fetch_token` must be called before this method. This method
+
+ constructs a `google.auth.transport.requests.AuthorizedSession`
+
+ class using this flow''s `credentials`.
+
+ '
+ syntax:
+ content: authorized_session()
+ parameters: []
+ returns:
+ - description: The constructed session.
+ var_type: google.auth.transport.requests.AuthorizedSession
+ type: method
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.authorized_session
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.client_config
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: client_config
+ source:
+ id: client_config
+ path: null
+ startLine: null
+ summary: 'The OAuth 2.0 client configuration.
+
+
+ :type: Mapping[str, Any]
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.client_config
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.client_type
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: client_type
+ source:
+ id: client_type
+ path: null
+ startLine: null
+ summary: 'The client type, either `''web''` or `''installed''`
+
+
+ :type: str
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.client_type
+- &id001
+ attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.credentials
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: credentials
+ source:
+ id: credentials
+ path: null
+ startLine: null
+ summary: 'Returns credentials from the OAuth 2.0 session.
+
+
+ `fetch_token` must be called before accessing this. This method
+
+ constructs a `google.oauth2.credentials.Credentials` class using
+
+ the session''s token and the client config.
+
+ '
+ syntax:
+ exceptions:
+ - description: If there is no access token in the session.
+ var_type: ValueError
+ returns:
+ - description: The constructed credentials.
+ var_type: google.oauth2.credentials.Credentials
+ type: property
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.credentials
+- *id001
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.fetch_token
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: fetch_token
+ source:
+ id: fetch_token
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 260
+ summary: 'Completes the Authorization Flow and obtains an access token.
+
+
+ This is the final step in the OAuth 2.0 Authorization Flow. This is
+
+ called after the user consents.
+
+
+ This method calls
+
+ `requests_oauthlib.OAuth2Session.fetch_token`
+
+ and specifies the client configuration''s token URI (usually Google''s
+
+ token server).
+
+ '
+ syntax:
+ content: fetch_token(**kwargs)
+ parameters: []
+ returns:
+ - description: The obtained tokens. Typically, you will not use return value of
+ this function and instead use credentials to obtain a google.auth.credentials.Credentials
+ instance.
+ var_type: Mapping[str, str]
+ type: method
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.fetch_token
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.from_client_config
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: from_client_config
+ source:
+ id: from_client_config
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 131
+ summary: 'Creates a `requests_oauthlib.OAuth2Session` from client
+
+ configuration loaded from a Google-format client secrets file.
+
+ '
+ syntax:
+ content: from_client_config(client_config, scopes, **kwargs)
+ exceptions:
+ - description: 'If the client configuration is not in the correct format. .. _client
+ secrets: https://github.com/googleapis/google-api-python-client/blob/main/docs/client-secrets.md'
+ var_type: ValueError
+ parameters:
+ - description: The client configuration in the Google client secrets_
+ format.
+ id: client_config
+ var_type: Mapping[str, Any]
+ - description: The list of scopes to request during the flow.
+ id: scopes
+ var_type: Sequence[str]
+ returns:
+ - description: The constructed Flow instance.
+ var_type: Flow
+ type: method
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.from_client_config
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: from_client_secrets_file
+ source:
+ id: from_client_secrets_file
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 183
+ summary: 'Creates a `Flow` instance from a Google client secrets file.
+
+ '
+ syntax:
+ content: from_client_secrets_file(client_secrets_file, scopes, **kwargs)
+ parameters:
+ - description: The path to the client secrets .json file.
+ id: client_secrets_file
+ var_type: str
+ - description: The list of scopes to request during the flow.
+ id: scopes
+ var_type: Sequence[str]
+ returns:
+ - description: The constructed Flow instance.
+ var_type: Flow
+ type: method
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.oauth2session
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: oauth2session
+ source:
+ id: oauth2session
+ path: null
+ startLine: null
+ summary: 'The OAuth 2.0 session.
+
+
+ :type: requests_oauthlib.OAuth2Session
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.oauth2session
+- &id002
+ attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.redirect_uri
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: redirect_uri
+ source:
+ id: redirect_uri
+ path: null
+ startLine: null
+ summary: 'The OAuth 2.0 redirect URI. Pass-through to
+
+ `self.oauth2session.redirect_uri`.
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.redirect_uri
+- *id002
+- attributes: []
+ class: google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: run_local_server
+ source:
+ id: run_local_server
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 371
+ summary: 'Run the flow using the server strategy.
+
+
+ The server strategy instructs the user to open the authorization URL in
+
+ their browser and will attempt to automatically open the URL for them.
+
+ It will start a local web server to listen for the authorization
+
+ response. Once authorization is complete the authorization server will
+
+ redirect the user''s browser to the local web server. The web server
+
+ will get the authorization code from the response and shutdown. The
+
+ code is then exchanged for a token.
+
+ '
+ syntax:
+ content: "run_local_server(\n host=\"localhost\",\n bind_addr=None,\n \
+ \ port=8080,\n authorization_prompt_message=\"Please visit this URL to authorize\
+ \ this application: {url}\",\n success_message=\"The authentication flow\
+ \ has completed. You may close this window.\",\n open_browser=True,\n \
+ \ redirect_uri_trailing_slash=True,\n timeout_seconds=None,\n **kwargs\n\
+ )"
+ parameters:
+ - description: The hostname for the local redirect server. This will be served
+ over http, not https.
+ id: host
+ var_type: str
+ - description: Optionally provide an ip address for the redirect server to listen
+ on when it is not the same as host (e.g. in a container). Default value is
+ None, which means that the redirect server will listen on the ip address specified
+ in the host parameter.
+ id: bind_addr
+ var_type: str
+ - description: The port for the local redirect server.
+ id: port
+ var_type: int
+ - description: The message to display to tell the user to navigate to the authorization
+ URL. If None or empty, don't display anything.
+ id: authorization_prompt_message
+ var_type: str None
+ - description: The message to display in the web browser the authorization flow
+ is complete.
+ id: success_message
+ var_type: str
+ - description: Whether or not to open the authorization URL in the user's browser.
+ id: open_browser
+ var_type: bool
+ - description: whether or not to add trailing slash when constructing the redirect_uri.
+ Default value is True.
+ id: redirect_uri_trailing_slash
+ var_type: bool
+ - description: It will raise an error after the timeout timing if there are no
+ credentials response. The value is in seconds. When set to None there is no
+ timeout. Default value is None.
+ id: timeout_seconds
+ var_type: int
+ returns:
+ - description: The OAuth 2.0 credentials for the user.
+ var_type: google.oauth2.credentials.Credentials
+ type: method
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
+references:
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow
+ isExternal: false
+ name: InstalledAppFlow
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.authorization_url
+ isExternal: false
+ name: authorization_url
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.authorization_url
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.authorized_session
+ isExternal: false
+ name: authorized_session
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.authorized_session
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.client_config
+ isExternal: false
+ name: client_config
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.client_config
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.client_type
+ isExternal: false
+ name: client_type
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.client_type
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.credentials
+ isExternal: false
+ name: credentials
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.credentials
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.fetch_token
+ isExternal: false
+ name: fetch_token
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.fetch_token
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.from_client_config
+ isExternal: false
+ name: from_client_config
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.from_client_config
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file
+ isExternal: false
+ name: from_client_secrets_file
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.oauth2session
+ isExternal: false
+ name: oauth2session
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.oauth2session
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.redirect_uri
+ isExternal: false
+ name: redirect_uri
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.redirect_uri
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
+ isExternal: false
+ name: run_local_server
+ parent: google_auth_oauthlib.flow.InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.yml
new file mode 100644
index 000000000000..71ea1a68e208
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.flow.yml
@@ -0,0 +1,46 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google_auth_oauthlib.flow.Flow
+ - google_auth_oauthlib.flow.InstalledAppFlow
+ fullName: google_auth_oauthlib.flow
+ langs:
+ - python
+ module: google_auth_oauthlib.flow
+ name: flow
+ source:
+ id: flow
+ path: tests/testdata/auth/google_auth_oauthlib/flow.py
+ startLine: 0
+ summary: "OAuth 2.0 Authorization Flow\n\nThis module provides integration with\
+ \ `requests-oauthlib`_ for running the\n`OAuth 2.0 Authorization Flow`_ and acquiring\
+ \ user credentials. See\n`Using OAuth 2.0 to Access Google APIs`_ for an overview\
+ \ of OAuth 2.0\nauthorization scenarios Google APIs support.\n\nHere's an example\
+ \ of using `InstalledAppFlow`::\n\n from google_auth_oauthlib.flow import InstalledAppFlow\n\
+ \n # Create the flow using the client secrets file from the Google API\n \
+ \ # Console.\n flow = InstalledAppFlow.from_client_secrets_file(\n \
+ \ 'client_secrets.json',\n scopes=['profile', 'email'])\n\n flow.run_local_server()\n\
+ \n # You can use flow.credentials, or you can just get a requests session\n\
+ \ # using flow.authorized_session.\n session = flow.authorized_session()\n\
+ \n profile_info = session.get(\n 'https://www.googleapis.com/userinfo/v2/me').json()\n\
+ \n print(profile_info)\n # {'name': '...', 'email': '...', ...}\n\n.. _requests-oauthlib:\
+ \ http://requests-oauthlib.readthedocs.io/en/latest/\n.. _OAuth 2.0 Authorization\
+ \ Flow:\n https://tools.ietf.org/html/rfc6749#section-1.2\n.. _Using OAuth\
+ \ 2.0 to Access Google APIs:\n https://developers.google.com/identity/protocols/oauth2\n\
+ \n"
+ syntax: {}
+ type: module
+ uid: google_auth_oauthlib.flow
+references:
+- fullName: google_auth_oauthlib.flow.Flow
+ isExternal: false
+ name: Flow
+ parent: google_auth_oauthlib.flow
+ uid: google_auth_oauthlib.flow.Flow
+- fullName: google_auth_oauthlib.flow.InstalledAppFlow
+ isExternal: false
+ name: InstalledAppFlow
+ parent: google_auth_oauthlib.flow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.helpers.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.helpers.yml
new file mode 100644
index 000000000000..65916ce807d7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.helpers.yml
@@ -0,0 +1,158 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google_auth_oauthlib.helpers.credentials_from_session
+ - google_auth_oauthlib.helpers.session_from_client_config
+ - google_auth_oauthlib.helpers.session_from_client_secrets_file
+ fullName: google_auth_oauthlib.helpers
+ langs:
+ - python
+ module: google_auth_oauthlib.helpers
+ name: helpers
+ source:
+ id: helpers
+ path: tests/testdata/auth/google_auth_oauthlib/helpers.py
+ startLine: 0
+ summary: 'Integration helpers.
+
+
+ This module provides helpers for integrating with `requests-oauthlib`_.
+
+ Typically, you''ll want to use the higher-level helpers in
+
+ `google_auth_oauthlib.flow `.
+
+
+ .. _requests-oauthlib: http://requests-oauthlib.readthedocs.io/en/latest/
+
+
+ '
+ syntax: {}
+ type: module
+ uid: google_auth_oauthlib.helpers
+- attributes: []
+ fullName: google_auth_oauthlib.helpers.credentials_from_session
+ langs:
+ - python
+ module: google_auth_oauthlib.helpers
+ name: credentials_from_session
+ source:
+ id: credentials_from_session
+ path: tests/testdata/auth/google_auth_oauthlib/helpers.py
+ startLine: 100
+ summary: 'Creates `google.oauth2.credentials.Credentials` from a
+
+ `requests_oauthlib.OAuth2Session`.
+
+
+ `fetch_token` must be called on the session before before calling
+
+ this. This uses the session''s auth token and the provided client
+
+ configuration to create `google.oauth2.credentials.Credentials`.
+
+ This allows you to use the credentials from the session with Google
+
+ API client libraries.
+
+ '
+ syntax:
+ content: credentials_from_session(session, client_config=None)
+ exceptions:
+ - description: If there is no access token in the session.
+ var_type: ValueError
+ parameters:
+ - description: The OAuth 2.0 session.
+ id: session
+ var_type: requests_oauthlib.OAuth2Session
+ - description: The subset of the client configuration to use. For example, if
+ you have a web client you would pass in client_config['web'].
+ id: client_config
+ var_type: Mapping[str, Any]
+ returns:
+ - description: The constructed credentials.
+ var_type: google.oauth2.credentials.Credentials
+ type: function
+ uid: google_auth_oauthlib.helpers.credentials_from_session
+- attributes: []
+ fullName: google_auth_oauthlib.helpers.session_from_client_config
+ langs:
+ - python
+ module: google_auth_oauthlib.helpers
+ name: session_from_client_config
+ source:
+ id: session_from_client_config
+ path: tests/testdata/auth/google_auth_oauthlib/helpers.py
+ startLine: 34
+ summary: 'Creates a `requests_oauthlib.OAuth2Session` from client
+
+ configuration loaded from a Google-format client secrets file.
+
+ '
+ syntax:
+ content: session_from_client_config(client_config, scopes, **kwargs)
+ exceptions:
+ - description: If the client configuration is not in the correct format.
+ var_type: ValueError
+ parameters:
+ - description: The client configuration in the Google client secrets_
+ format.
+ id: client_config
+ var_type: Mapping[str, Any]
+ - description: The list of scopes to request during the flow.
+ id: scopes
+ var_type: Sequence[str]
+ returns:
+ - description: The new oauthlib session and the validated client configuration.
+ var_type: 'Tuple[requests_oauthlib.OAuth2Session, Mapping[str, Any]] .. _client
+ secrets: https://github.com/googleapis/google-api-python-client/blob/main/docs/client-secrets.md'
+ type: function
+ uid: google_auth_oauthlib.helpers.session_from_client_config
+- attributes: []
+ fullName: google_auth_oauthlib.helpers.session_from_client_secrets_file
+ langs:
+ - python
+ module: google_auth_oauthlib.helpers
+ name: session_from_client_secrets_file
+ source:
+ id: session_from_client_secrets_file
+ path: tests/testdata/auth/google_auth_oauthlib/helpers.py
+ startLine: 75
+ summary: 'Creates a `requests_oauthlib.OAuth2Session` instance from a
+
+ Google-format client secrets file.
+
+ '
+ syntax:
+ content: session_from_client_secrets_file(client_secrets_file, scopes, **kwargs)
+ parameters:
+ - description: The path to the client secrets_ .json file.
+ id: client_secrets_file
+ var_type: str
+ - description: The list of scopes to request during the flow.
+ id: scopes
+ var_type: Sequence[str]
+ returns:
+ - description: The new oauthlib session and the validated client configuration.
+ var_type: 'Tuple[requests_oauthlib.OAuth2Session, Mapping[str, Any]] .. _client
+ secrets: https://github.com/googleapis/google-api-python-client/blob/main/docs/client-secrets.md'
+ type: function
+ uid: google_auth_oauthlib.helpers.session_from_client_secrets_file
+references:
+- fullName: google_auth_oauthlib.helpers.credentials_from_session
+ isExternal: false
+ name: credentials_from_session
+ parent: google_auth_oauthlib.helpers
+ uid: google_auth_oauthlib.helpers.credentials_from_session
+- fullName: google_auth_oauthlib.helpers.session_from_client_config
+ isExternal: false
+ name: session_from_client_config
+ parent: google_auth_oauthlib.helpers
+ uid: google_auth_oauthlib.helpers.session_from_client_config
+- fullName: google_auth_oauthlib.helpers.session_from_client_secrets_file
+ isExternal: false
+ name: session_from_client_secrets_file
+ parent: google_auth_oauthlib.helpers
+ uid: google_auth_oauthlib.helpers.session_from_client_secrets_file
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.tool.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.tool.yml
new file mode 100644
index 000000000000..408d475390b8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.tool.yml
@@ -0,0 +1,18 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ fullName: google_auth_oauthlib.tool
+ langs:
+ - python
+ module: google_auth_oauthlib.tool
+ name: tool
+ source:
+ id: tool
+ path: null
+ startLine: null
+ summary: API documentation for `tool` module.
+ syntax: {}
+ type: module
+ uid: google_auth_oauthlib.tool
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.yml
new file mode 100644
index 000000000000..1e52150b2e3c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/google_auth_oauthlib.yml
@@ -0,0 +1,118 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google_auth_oauthlib.get_user_credentials
+ - google_auth_oauthlib.flow
+ - google_auth_oauthlib.helpers
+ - google_auth_oauthlib.tool
+ fullName: google_auth_oauthlib
+ langs:
+ - python
+ module: google_auth_oauthlib
+ name: google_auth_oauthlib
+ source:
+ id: google_auth_oauthlib
+ path: tests/testdata/auth/google_auth_oauthlib/__init__.py
+ startLine: 0
+ summary: API documentation for `` package.
+ syntax: {}
+ type: subPackage
+ uid: google_auth_oauthlib
+- attributes: []
+ fullName: google_auth_oauthlib.get_user_credentials
+ langs:
+ - python
+ module: google_auth_oauthlib
+ name: get_user_credentials
+ source:
+ id: get_user_credentials
+ path: tests/testdata/auth/google_auth_oauthlib/interactive.py
+ startLine: 83
+ summary: 'Gets credentials associated with your Google user account.
+
+
+ This function authenticates using your user credentials by going through
+
+ the OAuth 2.0 flow. You''ll open a browser window to authenticate to your
+
+ Google account. The permissions it requests correspond to the scopes
+
+ you''ve provided.
+
+
+ To obtain the `client_id` and `client_secret`, create an **OAuth
+
+ client ID** with application type **Other** from the `Credentials page on
+
+ the Google Developer''s Console
+
+ `_. Learn more
+
+ with the `Authenticating as an end user
+
+ `_ guide.
+
+ '
+ syntax:
+ content: "get_user_credentials(\n scopes, client_id, client_secret, minimum_port=8080,\
+ \ maximum_port=None\n)"
+ parameters:
+ - description: A list of scopes to use when authenticating to Google APIs. See
+ the list of OAuth 2.0 scopes for Google APIs _.
+ id: scopes
+ var_type: Sequence[str]
+ - description: A string that identifies your application to Google APIs. Find
+ this value in the Credentials page on the Google Developer's Console
+ _.
+ id: client_id
+ var_type: str
+ - description: A string that verifies your application to Google APIs. Find this
+ value in the Credentials page on the Google Developer's Console _.
+ id: client_secret
+ var_type: str
+ - description: Beginning of range of ports to try for redirect URI HTTP server.
+ Defaults to 8080.
+ id: minimum_port
+ var_type: int
+ - description: End of range of ports to try (not including exactly equals stop).
+ This function tries 100 possible ports if no stop is specified.
+ id: maximum_port
+ var_type: Optional[int]
+ returns:
+ - description: The OAuth 2.0 credentials for the user.
+ var_type: 'google.oauth2.credentials.Credentials .. rubric:: Examples Get credentials
+ for your user account and use them to run a query with BigQuery:: import google_auth_oauthlib
+ # TODO: Create a client ID for your project. client_id = "YOUR-CLIENT-ID.apps.googleusercontent.com"
+ client_secret = "abc_ThIsIsAsEcReT" # TODO: Choose the needed scopes for your
+ applications. scopes = ["https://www.googleapis.com/auth/cloud-platform"]
+ credentials = google_auth_oauthlib.get_user_credentials( scopes, client_id,
+ client_secret ) # 1. Open the link. # 2. Authorize the application to have
+ access to your account. # 3. Copy and paste the authorization code to the
+ prompt. # Use the credentials to construct a client for Google APIs. from
+ google.cloud import bigquery bigquery_client = bigquery.Client( credentials=credentials,
+ project="your-project-id" ) print(list(bigquery_client.query("SELECT 1").result()))'
+ type: function
+ uid: google_auth_oauthlib.get_user_credentials
+references:
+- fullName: google_auth_oauthlib.get_user_credentials
+ isExternal: false
+ name: get_user_credentials
+ parent: google_auth_oauthlib
+ uid: google_auth_oauthlib.get_user_credentials
+- fullName: google_auth_oauthlib.flow
+ isExternal: false
+ name: flow
+ parent: google_auth_oauthlib
+ uid: google_auth_oauthlib.flow
+- fullName: google_auth_oauthlib.helpers
+ isExternal: false
+ name: helpers
+ parent: google_auth_oauthlib
+ uid: google_auth_oauthlib.helpers
+- fullName: google_auth_oauthlib.tool
+ isExternal: false
+ name: tool
+ parent: google_auth_oauthlib
+ uid: google_auth_oauthlib.tool
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/index.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/index.md
new file mode 100644
index 000000000000..bbd07d952c15
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/index.md
@@ -0,0 +1,28 @@
+# google-auth-oauthlib
+
+This library contains experimental [oauthlib](https://oauthlib.readthedocs.io) integration with [google-auth](https://google-auth.readthedocs.io).
+
+## Installing
+
+google-auth can be installed with [pip](https://pip.pypa.io):
+
+```default
+$ pip install --upgrade google-auth-oauthlib
+```
+
+google-auth-oauthlib is open-source, so you can alternatively grab the source
+code from [GitHub](https://github.com/GoogleCloudPlatform/google-auth-library-python-oauthlib) and install from source.
+
+## Usage
+
+Consult the [Module Reference](reference/modules.md) documentation.
+
+## License
+
+google-auth-oauthlib is made available under the Apache License, Version 2.0.
+For more details, see [LICENSE](https://github.com/GoogleCloudPlatform/google-auth-library-python-oauthlib/LICENSE)
+
+## Contributing
+
+We happily welcome contributions, please see our [contributing](https://github.com/GoogleCloudPlatform/google-auth-library-python/CONTRIBUTING.rst) documentation
+for details.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/toc.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/toc.yml
new file mode 100644
index 000000000000..915079f6b72c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/auth/toc.yml
@@ -0,0 +1,24 @@
+- items:
+ - href: index.md
+ name: Overview
+ - items:
+ - items:
+ - name: Overview
+ uid: google_auth_oauthlib
+ - items:
+ - name: Overview
+ uid: google_auth_oauthlib.flow
+ - name: Flow
+ uid: google_auth_oauthlib.flow.Flow
+ - name: InstalledAppFlow
+ uid: google_auth_oauthlib.flow.InstalledAppFlow
+ name: flow
+ uid: google_auth_oauthlib.flow
+ - name: helpers
+ uid: google_auth_oauthlib.helpers
+ - name: tool
+ uid: google_auth_oauthlib.tool
+ name: google_auth_oauthlib
+ uid: google_auth_oauthlib
+ name: Google Auth Oauthlib
+ name: google-auth-oauthlib
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/changelog.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/changelog.md
new file mode 100644
index 000000000000..4019c1309b9c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/changelog.md
@@ -0,0 +1,489 @@
+# Changelog
+
+[PyPI History](https://pypi.org/project/google-cloud-texttospeech/#history)
+
+## [2.12.3](https://github.com/googleapis/python-texttospeech/compare/v2.12.2...v2.12.3) (2022-10-07)
+
+### Bug Fixes
+
+
+* **deps:** Allow protobuf 3.19.5 ([#338](https://github.com/googleapis/python-texttospeech/issues/338)) ([aa92121](https://github.com/googleapis/python-texttospeech/commit/aa921215c05588b6555b7b41381b30f8b0079d54))
+
+## [2.12.2](https://github.com/googleapis/python-texttospeech/compare/v2.12.1...v2.12.2) (2022-10-03)
+
+### Bug Fixes
+
+
+* **deps:** Require protobuf >= 3.20.2 ([#335](https://github.com/googleapis/python-texttospeech/issues/335)) ([50b394d](https://github.com/googleapis/python-texttospeech/commit/50b394dc5684b2df6cf544ba7bb5296d384ee0f8))
+
+## [2.12.1](https://github.com/googleapis/python-texttospeech/compare/v2.12.0...v2.12.1) (2022-08-11)
+
+### Bug Fixes
+
+
+* **deps:** allow protobuf < 5.0.0 ([#316](https://github.com/googleapis/python-texttospeech/issues/316)) ([ec75f1e](https://github.com/googleapis/python-texttospeech/commit/ec75f1e5382bd527d17fb347a7ecc7cd35f57ab0))
+
+
+* **deps:** require proto-plus >= 1.22.0 ([ec75f1e](https://github.com/googleapis/python-texttospeech/commit/ec75f1e5382bd527d17fb347a7ecc7cd35f57ab0))
+
+## [2.12.0](https://github.com/googleapis/python-texttospeech/compare/v2.11.1...v2.12.0) (2022-07-16)
+
+### Features
+
+
+* add audience parameter ([f450551](https://github.com/googleapis/python-texttospeech/commit/f450551482e52c7f5564bf735b705e22255dc5d8))
+
+### Bug Fixes
+
+
+* **deps:** require google-api-core>=1.32.0,>=2.8.0 ([#304](https://github.com/googleapis/python-texttospeech/issues/304)) ([f450551](https://github.com/googleapis/python-texttospeech/commit/f450551482e52c7f5564bf735b705e22255dc5d8))
+
+
+* require python 3.7+ ([#306](https://github.com/googleapis/python-texttospeech/issues/306)) ([192277b](https://github.com/googleapis/python-texttospeech/commit/192277b9b62338840b55fe8e24be582a19f390cd))
+
+## [2.11.1](https://github.com/googleapis/python-texttospeech/compare/v2.11.0...v2.11.1) (2022-06-06)
+
+### Bug Fixes
+
+
+* **deps:** require protobuf <4.0.0dev ([#293](https://github.com/googleapis/python-texttospeech/issues/293)) ([e5ab0d6](https://github.com/googleapis/python-texttospeech/commit/e5ab0d6b69e008653b1500742ede3ead3a748f58))
+
+### Documentation
+
+
+* fix changelog header to consistent size ([#294](https://github.com/googleapis/python-texttospeech/issues/294)) ([8a8b65c](https://github.com/googleapis/python-texttospeech/commit/8a8b65c0e4c39a5671e9998848ebb89ea38d301d))
+
+## [2.11.0](https://github.com/googleapis/python-texttospeech/compare/v2.10.2...v2.11.0) (2022-03-10)
+
+### Features
+
+
+* promote CustomVoiceParams to v1 ([#266](https://github.com/googleapis/python-texttospeech/issues/266)) ([f484e7f](https://github.com/googleapis/python-texttospeech/commit/f484e7fe036fe57a4f432bf30c6421a6541ea486))
+
+## [2.10.2](https://github.com/googleapis/python-texttospeech/compare/v2.10.1...v2.10.2) (2022-03-05)
+
+### Bug Fixes
+
+
+* **deps:** require google-api-core>=1.31.5, >=2.3.2 ([#261](https://github.com/googleapis/python-texttospeech/issues/261)) ([f993058](https://github.com/googleapis/python-texttospeech/commit/f993058b1535e8cc0c71877b8dca9beae3dffb1b))
+
+
+* **deps:** require proto-plus>=1.15.0 ([f993058](https://github.com/googleapis/python-texttospeech/commit/f993058b1535e8cc0c71877b8dca9beae3dffb1b))
+
+## [2.10.1](https://github.com/googleapis/python-texttospeech/compare/v2.10.0...v2.10.1) (2022-02-26)
+
+### Documentation
+
+
+* add generated snippets ([#249](https://github.com/googleapis/python-texttospeech/issues/249)) ([f918e82](https://github.com/googleapis/python-texttospeech/commit/f918e82df2e0c499356fa1e095b13f7ac2cd3b6b))
+
+## [2.10.0](https://github.com/googleapis/python-texttospeech/compare/v2.9.1...v2.10.0) (2022-02-03)
+
+### Features
+
+
+* add api key support ([#242](https://github.com/googleapis/python-texttospeech/issues/242)) ([3b4f0d0](https://github.com/googleapis/python-texttospeech/commit/3b4f0d0749529b04ed7fedec3c4b06b6d42c12cd))
+
+### Bug Fixes
+
+
+* resolve DuplicateCredentialArgs error when using credentials_file ([4c11b12](https://github.com/googleapis/python-texttospeech/commit/4c11b127ece0009082fe91062f3f36c8f18e8ffc))
+
+### Documentation
+
+
+* update comments for ListVoicesRequest ([#244](https://github.com/googleapis/python-texttospeech/issues/244)) ([bc5b73f](https://github.com/googleapis/python-texttospeech/commit/bc5b73fbc62900f89a01486c6e8d42d459c34fd6))
+
+## [2.9.1](https://www.github.com/googleapis/python-texttospeech/compare/v2.9.0...v2.9.1) (2022-01-08)
+
+### Documentation
+
+
+* Added virtualenv comment for clarity ([#225](https://www.github.com/googleapis/python-texttospeech/issues/225)) ([61a7fce](https://www.github.com/googleapis/python-texttospeech/commit/61a7fcec0611712cdb1692b830db4aaca4d411b0))
+
+
+* update comments for ListVoicesRequest ([#229](https://www.github.com/googleapis/python-texttospeech/issues/229)) ([9ea340c](https://www.github.com/googleapis/python-texttospeech/commit/9ea340cee20298630a6a15bed0ed2df9f69b3d13))
+
+## [2.9.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.8.0...v2.9.0) (2021-11-16)
+
+### Features
+
+
+* update v1 proto ([#221](https://www.github.com/googleapis/python-texttospeech/issues/221)) ([e8776d7](https://www.github.com/googleapis/python-texttospeech/commit/e8776d7a482f495ed5ae0e1235609e3e2d3e6067))
+
+## [2.8.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.7.1...v2.8.0) (2021-11-13)
+
+### Features
+
+
+* **v1beta1:** add CustomVoiceParams ([#215](https://www.github.com/googleapis/python-texttospeech/issues/215)) ([6a18d0f](https://www.github.com/googleapis/python-texttospeech/commit/6a18d0f097e992bd4d90eaf5032ce98aa4af004a))
+
+### Documentation
+
+
+* fix docstring formatting ([#218](https://www.github.com/googleapis/python-texttospeech/issues/218)) ([2c57f95](https://www.github.com/googleapis/python-texttospeech/commit/2c57f95a1af747b49dac41628bd43d485a68583e))
+
+## [2.7.1](https://www.github.com/googleapis/python-texttospeech/compare/v2.7.0...v2.7.1) (2021-11-01)
+
+### Bug Fixes
+
+
+* **deps:** drop packaging dependency ([99ac70b](https://www.github.com/googleapis/python-texttospeech/commit/99ac70ba45d7c500d0f19a30dead060c0db4453c))
+
+
+* **deps:** require google-api-core >= 1.28.0 ([99ac70b](https://www.github.com/googleapis/python-texttospeech/commit/99ac70ba45d7c500d0f19a30dead060c0db4453c))
+
+### Documentation
+
+
+* list oneofs in docstring ([99ac70b](https://www.github.com/googleapis/python-texttospeech/commit/99ac70ba45d7c500d0f19a30dead060c0db4453c))
+
+## [2.7.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.6.0...v2.7.0) (2021-10-18)
+
+### Features
+
+
+* add support for python 3.10 ([#202](https://www.github.com/googleapis/python-texttospeech/issues/202)) ([2ffa70b](https://www.github.com/googleapis/python-texttospeech/commit/2ffa70b6c35707142d66476b0ef5e3bd8d6d0052))
+
+## [2.6.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.3...v2.6.0) (2021-10-07)
+
+### Features
+
+
+* add context manager support in client ([#196](https://www.github.com/googleapis/python-texttospeech/issues/196)) ([73d9290](https://www.github.com/googleapis/python-texttospeech/commit/73d9290cdea69a00ba317ae017a1d07bcf734989))
+
+## [2.5.3](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.2...v2.5.3) (2021-09-24)
+
+### Bug Fixes
+
+
+* add ‘dict’ annotation type to ‘request’ ([e74b994](https://www.github.com/googleapis/python-texttospeech/commit/e74b9942d480bf7e360bc61ff183909873fc20a6))
+
+## [2.5.2](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.1...v2.5.2) (2021-07-28)
+
+### Bug Fixes
+
+
+* enable self signed jwt for grpc ([#171](https://www.github.com/googleapis/python-texttospeech/issues/171)) ([9c1c437](https://www.github.com/googleapis/python-texttospeech/commit/9c1c4371caa712a749b406257c09d98f6b428e7b))
+
+### Documentation
+
+
+* add Samples section to CONTRIBUTING.rst ([#166](https://www.github.com/googleapis/python-texttospeech/issues/166)) ([053abe3](https://www.github.com/googleapis/python-texttospeech/commit/053abe3afc1107bdacd164e6ca4cd60b5ca07df7))
+
+### Miscellaneous Chores
+
+
+* release as 2.5.2 ([#172](https://www.github.com/googleapis/python-texttospeech/issues/172)) ([3804727](https://www.github.com/googleapis/python-texttospeech/commit/3804727995d0357fa0c4c5c246210768e0ce7124))
+
+## [2.5.1](https://www.github.com/googleapis/python-texttospeech/compare/v2.5.0...v2.5.1) (2021-07-20)
+
+### Bug Fixes
+
+
+* **deps:** pin ‘google-{api,cloud}-core’, ‘google-auth’ to allow 2.x versions ([#165](https://www.github.com/googleapis/python-texttospeech/issues/165)) ([d78b384](https://www.github.com/googleapis/python-texttospeech/commit/d78b384d302a1976682f35875ce2d4f7b60d7a6c))
+
+## [2.5.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.4.0...v2.5.0) (2021-07-01)
+
+### Features
+
+
+* add always_use_jwt_access ([#155](https://www.github.com/googleapis/python-texttospeech/issues/155)) ([cd10c37](https://www.github.com/googleapis/python-texttospeech/commit/cd10c3704db610f2abf65c9142cfdaa867d8490a))
+
+### Bug Fixes
+
+
+* disable always_use_jwt_access ([#159](https://www.github.com/googleapis/python-texttospeech/issues/159)) ([d109303](https://www.github.com/googleapis/python-texttospeech/commit/d109303898facc663a6e7fe9212440831c1eeb75))
+
+### Documentation
+
+
+* omit mention of Python 2.7 in ‘CONTRIBUTING.rst’ ([#1127](https://www.github.com/googleapis/python-texttospeech/issues/1127)) ([#150](https://www.github.com/googleapis/python-texttospeech/issues/150)) ([d2954ba](https://www.github.com/googleapis/python-texttospeech/commit/d2954ba91385db6d581f75154fb11c969f6ca0e2)), closes [#1126](https://www.github.com/googleapis/python-texttospeech/issues/1126)
+
+## [2.4.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.3.0...v2.4.0) (2021-05-28)
+
+### Features
+
+
+* support self-signed JWT flow for service accounts ([8a08836](https://www.github.com/googleapis/python-texttospeech/commit/8a08836487c1b7e4e58d3c07a4e26005d40793f0))
+
+### Bug Fixes
+
+
+* add async client to %name_%version/init.py ([8a08836](https://www.github.com/googleapis/python-texttospeech/commit/8a08836487c1b7e4e58d3c07a4e26005d40793f0))
+
+## [2.3.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.2.0...v2.3.0) (2021-03-31)
+
+### Features
+
+
+* add `from_service_account_info` to clients ([139e6e8](https://www.github.com/googleapis/python-texttospeech/commit/139e6e8511cdce4c0be7983520f7efc47092f3b1))
+
+
+* Add ALAW support on client library and improve the ListVoiceRequest message’s documentation ([#113](https://www.github.com/googleapis/python-texttospeech/issues/113)) ([8bbd380](https://www.github.com/googleapis/python-texttospeech/commit/8bbd38014fe796b30f4b12ae9432d3a05c130063))
+
+
+* add common resource helper methods ([139e6e8](https://www.github.com/googleapis/python-texttospeech/commit/139e6e8511cdce4c0be7983520f7efc47092f3b1))
+
+
+* support custom client info ([#82](https://www.github.com/googleapis/python-texttospeech/issues/82)) ([0612793](https://www.github.com/googleapis/python-texttospeech/commit/06127932a920f6318db8f25d6430755b35d09bb5))
+
+### Bug Fixes
+
+
+* change default retry and timeout settings ([139e6e8](https://www.github.com/googleapis/python-texttospeech/commit/139e6e8511cdce4c0be7983520f7efc47092f3b1))
+
+### Documentation
+
+
+* use sphinx-1.5.5 for sphinx-docfx-yaml ([#89](https://www.github.com/googleapis/python-texttospeech/issues/89)) ([feb04c5](https://www.github.com/googleapis/python-texttospeech/commit/feb04c50b56c2c3359b92d8b5887c8ee50be2b95))
+
+## [2.2.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.1.0...v2.2.0) (2020-08-10)
+
+### Features
+
+
+* incorporate upstream changes ([#73](https://www.github.com/googleapis/python-texttospeech/issues/73)) ([8ee5447](https://www.github.com/googleapis/python-texttospeech/commit/8ee544740f18497d9925bcf77e5ab96695503589))
+
+
+ * support MULAW audio encoding
+
+
+ * support MP3_64_KBPS audio encoding
+
+
+ * support timepointing via SSML tag
+
+
+ * support quota_project_id
+
+## [2.1.0](https://www.github.com/googleapis/python-texttospeech/compare/v2.0.0...v2.1.0) (2020-06-20)
+
+### Features
+
+
+* add async client ([#53](https://www.github.com/googleapis/python-texttospeech/issues/53)) ([887d8d5](https://www.github.com/googleapis/python-texttospeech/commit/887d8d501ce9255fee44170b5fc40ebfb1ea953d))
+
+### Documentation
+
+
+* change relative URLs to absolute URLs to fix broken links ([#40](https://www.github.com/googleapis/python-texttospeech/issues/40)) ([b68df44](https://www.github.com/googleapis/python-texttospeech/commit/b68df446daa7983cad1d31553ece6df569c932b2))
+
+## [2.0.0](https://www.github.com/googleapis/python-texttospeech/compare/v1.0.1...v2.0.0) (2020-06-01)
+
+### ⚠ BREAKING CHANGES
+
+
+* This release has breaking changes. See the [2.0.0 Migration Guide](https://github.com/googleapis/python-texttospeech/blob/main/UPGRADING.md#200-migration-guide) for details.
+
+### Features
+
+
+* regenerate with microgenerator ([#30](https://www.github.com/googleapis/python-texttospeech/issues/30)) ([3181b55](https://www.github.com/googleapis/python-texttospeech/commit/3181b55733da7aecde37009a0dd77117434deceb))
+
+### Bug Fixes
+
+
+* address PR comments ([65f903b](https://www.github.com/googleapis/python-texttospeech/commit/65f903b00395716fad272ca4fc973755735e1e20))
+
+## [1.0.1](https://www.github.com/googleapis/python-texttospeech/compare/v1.0.0...v1.0.1) (2020-02-28)
+
+### Bug Fixes
+
+
+* update url in setup.py ([#13](https://www.github.com/googleapis/python-texttospeech/issues/13)) ([dc17707](https://www.github.com/googleapis/python-texttospeech/commit/dc17707c41feb885d94f1045ef14e4b9e0898716))
+
+## [1.0.0](https://www.github.com/googleapis/python-texttospeech/compare/v0.5.0...v1.0.0) (2020-02-28)
+
+### Features
+
+
+* bump release status to GA ([#9](https://www.github.com/googleapis/python-texttospeech/issues/9)) ([03a639e](https://www.github.com/googleapis/python-texttospeech/commit/03a639e16256d9211c1fe88991440f2cc22eccd6))
+
+## 0.5.0
+
+07-24-2019 17:48 PDT
+
+### Implementation Changes
+
+
+* Allow kwargs to be passed to create_channel (via synth). ([#8407](https://github.com/googleapis/google-cloud-python/pull/8407))
+
+
+* Reformat protos, update nox session docs (via synth). ([#7941](https://github.com/googleapis/google-cloud-python/pull/7941))
+
+
+* Remove classifier for Python 3.4 for end-of-life. ([#7535](https://github.com/googleapis/google-cloud-python/pull/7535))
+
+### New Features
+
+
+* Add ‘client_options’ support (via synth). ([#8525](https://github.com/googleapis/google-cloud-python/pull/8525))
+
+### Dependencies
+
+
+* Bump minimum version for google-api-core to 1.14.0. ([#8709](https://github.com/googleapis/google-cloud-python/pull/8709))
+
+### Documentation
+
+
+* Link to googleapis.dev documentation in READMEs. ([#8705](https://github.com/googleapis/google-cloud-python/pull/8705))
+
+
+* Add compatibility check badges to READMEs. ([#8288](https://github.com/googleapis/google-cloud-python/pull/8288))
+
+
+* Repair top-level API reference page. ([#8435](https://github.com/googleapis/google-cloud-python/pull/8435))
+
+
+* Updated client library documentation URLs. ([#7307](https://github.com/googleapis/google-cloud-python/pull/7307))
+
+### Internal / Testing Changes
+
+
+* Pin black version (via synth). ([#8599](https://github.com/googleapis/google-cloud-python/pull/8599))
+
+
+* Add docs job to publish to googleapis.dev. ([#8464](https://github.com/googleapis/google-cloud-python/pull/8464))
+
+
+* Declare encoding as utf-8 in pb2 files (via synth). ([#8367](https://github.com/googleapis/google-cloud-python/pull/8367))
+
+
+* Add disclaimer to auto-generated template files (via synth). ([#8331](https://github.com/googleapis/google-cloud-python/pull/8331))
+
+
+* Blacken (via synth). ([#8281](https://github.com/googleapis/google-cloud-python/pull/8281))
+
+## 0.4.0
+
+02-07-2019 15:21 PST
+
+### Implementation Changes
+
+
+* Pick up stub docstring fix in GAPIC generator. ([#6984](https://github.com/googleapis/google-cloud-python/pull/6984))
+
+### New Features
+
+
+* Protoc updates to include effects_profile_id. ([#7097](https://github.com/googleapis/google-cloud-python/pull/7097))
+
+### Documentation
+
+
+* Fix `Client Library Documentation` link ([#7109](https://github.com/googleapis/google-cloud-python/pull/7109))
+
+### Internal / Testing Changes
+
+
+* Copy proto files alongside protoc versions.
+
+
+* Add protos as an artifact to library ([#7205](https://github.com/googleapis/google-cloud-python/pull/7205))
+
+
+* Update copyright headers and docstring quoting
+
+## 0.3.0
+
+12-18-2018 09:54 PST
+
+### Implementation Changes
+
+
+* Import `iam.policy` from `google.api_core`. ([#6741](https://github.com/googleapis/google-cloud-python/pull/6741))
+
+
+* Pick up fixes to GAPIC generator. ([#6510](https://github.com/googleapis/google-cloud-python/pull/6510))
+
+
+* Fix `client_info` bug, update docstrings. ([#6423](https://github.com/googleapis/google-cloud-python/pull/6423))
+
+
+* Re-generate library using texttospeech/synth.py ([#5981](https://github.com/googleapis/google-cloud-python/pull/5981))
+
+
+* Add gRPC Transport layer. ([#5959](https://github.com/googleapis/google-cloud-python/pull/5959))
+
+### Dependencies
+
+
+* Bump minimum `api_core` version for all GAPIC libs to 1.4.1. ([#6391](https://github.com/googleapis/google-cloud-python/pull/6391))
+
+
+* Avoid broken ‘google-common-apis 1.5.4’ release. ([#6355](https://github.com/googleapis/google-cloud-python/pull/6355))
+
+### Documentation
+
+
+* Document Python 2 deprecation ([#6910](https://github.com/googleapis/google-cloud-python/pull/6910))
+
+
+* Docs: normalize use of support level badges ([#6159](https://github.com/googleapis/google-cloud-python/pull/6159))
+
+
+* Docs: Replace links to `/stable/` with `/latest/`. ([#5901](https://github.com/googleapis/google-cloud-python/pull/5901))
+
+
+* Fix docs links for TTS. ([#5483](https://github.com/googleapis/google-cloud-python/pull/5483))
+
+### Internal / Testing Changes
+
+
+* Add synth.metadata. ([#6870](https://github.com/googleapis/google-cloud-python/pull/6870))
+
+
+* Update noxfile.
+
+
+* blacken all gen’d libs ([#6792](https://github.com/googleapis/google-cloud-python/pull/6792))
+
+
+* omit local deps ([#6701](https://github.com/googleapis/google-cloud-python/pull/6701))
+
+
+* Run black at end of synth.py ([#6698](https://github.com/googleapis/google-cloud-python/pull/6698))
+
+
+* Run Black on Generated libraries ([#6666](https://github.com/googleapis/google-cloud-python/pull/6666))
+
+
+* Add templates for flake8, coveragerc, noxfile, and black. ([#6642](https://github.com/googleapis/google-cloud-python/pull/6642))
+
+
+* Add ‘mock’ to unit test dependencies for autogen libs. ([#6402](https://github.com/googleapis/google-cloud-python/pull/6402))
+
+
+* Add / fix badges for PyPI / versions. ([#6158](https://github.com/googleapis/google-cloud-python/pull/6158))
+
+
+* Use new Nox ([#6175](https://github.com/googleapis/google-cloud-python/pull/6175))
+
+## 0.2.0
+
+### New Features
+
+
+* Add the text-to-speech v1 API surface. (#5468)
+
+
+* Re-generate the text-to-speech v1beta1 API surface. (#5468)
+
+### Documentation
+
+
+* Rename releases to changelog and include from CHANGELOG.md (#5191)
+
+### Internal / Testing Changes
+
+
+* Add Test runs for Python 3.7 and remove 3.4 (#5295)
+
+## 0.1.0
+
+### Interface additions
+
+
+* Added text-to-speech v1beta1. (#5049)
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.yml
new file mode 100644
index 000000000000..7815913e456c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.yml
@@ -0,0 +1,761 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.transport
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: TextToSpeechAsyncClient
+ source:
+ id: TextToSpeechAsyncClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 41
+ summary: 'Service that implements Google Cloud Text-to-Speech API.
+
+
+ '
+ syntax:
+ content: 'TextToSpeechAsyncClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Union[str, google.cloud.texttospeech_v1.services.text_to_speech.transports.base.TextToSpeechTransport]
+ = ''grpc_asyncio'', client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: TextToSpeechAsyncClient
+ source:
+ id: TextToSpeechAsyncClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 41
+ summary: 'Instantiates the text to speech client.
+
+ '
+ syntax:
+ content: 'TextToSpeechAsyncClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Union[str, google.cloud.texttospeech_v1.services.text_to_speech.transports.base.TextToSpeechTransport]
+ = ''grpc_asyncio'', client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ exceptions:
+ - description: If mutual TLS transport creation failed for any reason.
+ var_type: google.auth.exceptions.MutualTlsChannelError
+ parameters:
+ - description: The authorization credentials to attach to requests. These credentials
+ identify the application to the service; if none are specified, the client
+ will attempt to ascertain the credentials from the environment.
+ id: credentials
+ var_type: Optional[google.auth.credentials.Credentials]
+ - description: The transport to use. If set to None, a transport is chosen automatically.
+ id: transport
+ var_type: Union[str, .TextToSpeechTransport]
+ - description: 'Custom options for the client. It won''t take effect if a transport
+ instance is provided. (1) The api_endpoint property can be used
+ to override the default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint: "always" (always
+ use the default mTLS endpoint), "never" (always use the default regular endpoint)
+ and "auto" (auto switch to the default mTLS endpoint if client certificate
+ is present, this is the default value). However, the api_endpoint
+ property takes precedence if provided. (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ environment variable is "true", then the client_cert_source property
+ can be used to provide client certificate for mutual TLS transport. If not
+ provided, the default SSL client certificate will be used if present. If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ is "false" or not set, no client certificate will be used.'
+ id: client_options
+ var_type: ClientOptions
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_billing_account_path
+ source:
+ id: common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 185
+ summary: 'Returns a fully-qualified billing_account string.
+
+
+ '
+ syntax:
+ content: 'common_billing_account_path(billing_account: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_folder_path
+ source:
+ id: common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 200
+ summary: 'Returns a fully-qualified folder string.
+
+
+ '
+ syntax:
+ content: 'common_folder_path(folder: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_location_path
+ source:
+ id: common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 245
+ summary: 'Returns a fully-qualified location string.
+
+
+ '
+ syntax:
+ content: 'common_location_path(project: str, location: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_organization_path
+ source:
+ id: common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 215
+ summary: 'Returns a fully-qualified organization string.
+
+
+ '
+ syntax:
+ content: 'common_organization_path(organization: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_project_path
+ source:
+ id: common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 230
+ summary: 'Returns a fully-qualified project string.
+
+
+ '
+ syntax:
+ content: 'common_project_path(project: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: from_service_account_file
+ source:
+ id: from_service_account_file
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 87
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_file(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechAsyncClient
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: from_service_account_info
+ source:
+ id: from_service_account_info
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 72
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ info.\n"
+ syntax:
+ content: 'from_service_account_info(info: dict, *args, **kwargs)'
+ parameters:
+ - description: The service account private key info.
+ id: info
+ var_type: dict
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechAsyncClient
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: from_service_account_json
+ source:
+ id: from_service_account_json
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 87
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_json(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechAsyncClient
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: get_mtls_endpoint_and_cert_source
+ source:
+ id: get_mtls_endpoint_and_cert_source
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 105
+ summary: 'Return the API endpoint and client cert source for mutual TLS.
+
+
+ The client cert source is determined in the following order:
+
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true",
+ the
+
+ client cert source is None.
+
+ (2) if `client_options.client_cert_source` is provided, use the provided one;
+ if the
+
+ default client cert source exists, use the default one; otherwise the client cert
+
+ source is None.
+
+
+ The API endpoint is determined in the following order:
+
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use
+ the
+
+ default mTLS endpoint; if the environment variabel is "never", use the default
+ API
+
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint,
+ otherwise
+
+ use the default API endpoint.
+
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ '
+ syntax:
+ content: "get_mtls_endpoint_and_cert_source(\n client_options: typing.Optional[\n\
+ \ google.api_core.client_options.ClientOptions\n ] = None,\n)"
+ exceptions:
+ - description: If any errors happen.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - defaultValue: None
+ description: Custom options for the client. Only the api_endpoint
+ and client_cert_source properties may be used in this method.
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ returns:
+ - description: returns the API endpoint and the client cert source to use.
+ var_type: Tuple[str, Callable[[], Tuple[bytes, bytes]]]
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: get_transport_class
+ source:
+ id: get_transport_class
+ path: null
+ startLine: null
+ summary: 'Returns an appropriate transport class.
+
+ '
+ syntax:
+ content: "get_transport_class() -> typing.Type[\n google.cloud.texttospeech_v1.services.text_to_speech.transports.base.TextToSpeechTransport\n\
+ ]"
+ parameters:
+ - defaultValue: None
+ description: The name of the desired transport. If none is provided, then the
+ first transport in the registry is used.
+ id: label
+ var_type: str
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: list_voices
+ source:
+ id: list_voices
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 201
+ summary: "Returns a list of Voice supported for synthesis.\n\n```python\n# This\
+ \ snippet has been automatically generated and should be regarded as a\n# code\
+ \ template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1\n\nasync def sample_list_voices():\n\
+ \ # Create a client\n client = texttospeech_v1.TextToSpeechAsyncClient()\n\
+ \n # Initialize request argument(s)\n request = texttospeech_v1.ListVoicesRequest(\n\
+ \ )\n\n # Make the request\n response = await client.list_voices(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "list_voices(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1.types.cloud_tts.ListVoicesRequest,\
+ \ dict\n ]\n ] = None,\n *,\n language_code: typing.Optional[str]\
+ \ = None,\n retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.texttospeech_v1.types.cloud_tts.ListVoicesResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the ListVoices method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1.types.ListVoicesRequest ,
+ dict]
+ - description: Optional. Recommended. BCP-47 __
+ language tag. If not specified, the API will return all supported voices.
+ If specified, the ListVoices call will only return voices that can be used
+ to synthesize this language_code. For example, if you specify "en-NZ",
+ all "en-NZ" voices will be returned. If you specify "no",
+ both "no-\*" (Norwegian) and "nb-\*" (Norwegian
+ Bokmal) voices will be returned. This corresponds to the language_code
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: language_code
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the ListVoices method.
+ var_type: google.cloud.texttospeech_v1.types.ListVoicesResponse
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: model_path
+ source:
+ id: model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 163
+ summary: 'Returns a fully-qualified model string.
+
+
+ '
+ syntax:
+ content: 'model_path(project: str, location: str, model: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_billing_account_path
+ source:
+ id: parse_common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 194
+ summary: 'Parse a billing_account path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_billing_account_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_folder_path
+ source:
+ id: parse_common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 209
+ summary: 'Parse a folder path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_folder_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_location_path
+ source:
+ id: parse_common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 256
+ summary: 'Parse a location path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_location_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_organization_path
+ source:
+ id: parse_common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 224
+ summary: 'Parse a organization path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_organization_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_project_path
+ source:
+ id: parse_common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 239
+ summary: 'Parse a project path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_project_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_model_path
+ source:
+ id: parse_model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 176
+ summary: 'Parses a model path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_model_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: synthesize_speech
+ source:
+ id: synthesize_speech
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/async_client.py
+ startLine: 303
+ summary: "Synthesizes speech synchronously: receive results\nafter all text input\
+ \ has been processed.\n\n```python\n# This snippet has been automatically generated\
+ \ and should be regarded as a\n# code template only.\n# It will require modifications\
+ \ to work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1\n\nasync def sample_synthesize_speech():\n\
+ \ # Create a client\n client = texttospeech_v1.TextToSpeechAsyncClient()\n\
+ \n # Initialize request argument(s)\n input = texttospeech_v1.SynthesisInput()\n\
+ \ input.text = \"text_value\"\n\n voice = texttospeech_v1.VoiceSelectionParams()\n\
+ \ voice.language_code = \"language_code_value\"\n\n audio_config = texttospeech_v1.AudioConfig()\n\
+ \ audio_config.audio_encoding = \"ALAW\"\n\n request = texttospeech_v1.SynthesizeSpeechRequest(\n\
+ \ input=input,\n voice=voice,\n audio_config=audio_config,\n\
+ \ )\n\n # Make the request\n response = await client.synthesize_speech(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "synthesize_speech(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1.types.cloud_tts.SynthesizeSpeechRequest,\
+ \ dict\n ]\n ] = None,\n *,\n input: typing.Optional[\n \
+ \ google.cloud.texttospeech_v1.types.cloud_tts.SynthesisInput\n ] = None,\n\
+ \ voice: typing.Optional[\n google.cloud.texttospeech_v1.types.cloud_tts.VoiceSelectionParams\n\
+ \ ] = None,\n audio_config: typing.Optional[\n google.cloud.texttospeech_v1.types.cloud_tts.AudioConfig\n\
+ \ ] = None,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.cloud.texttospeech_v1.types.cloud_tts.SynthesizeSpeechResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the SynthesizeSpeech method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest ,
+ dict]
+ - description: Required. The Synthesizer requires either plain text or SSML as
+ input. This corresponds to the input field on the request
+ instance; if request is provided, this should not be set.
+ id: input
+ var_type: SynthesisInput
+ - description: Required. The desired voice of the synthesized audio. This corresponds
+ to the voice field on the request instance; if request
+ is provided, this should not be set.
+ id: voice
+ var_type: VoiceSelectionParams
+ - description: Required. The configuration of the synthesized audio. This corresponds
+ to the audio_config field on the request instance;
+ if request is provided, this should not be set.
+ id: audio_config
+ var_type: AudioConfig
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the SynthesizeSpeech method.
+ var_type: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+- &id001
+ attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.transport
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: transport
+ source:
+ id: transport
+ path: null
+ startLine: null
+ summary: 'Returns the transport used by the client instance.
+
+ '
+ syntax:
+ returns:
+ - description: The transport used by the client instance.
+ var_type: TextToSpeechTransport
+ type: property
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.transport
+- *id001
+references:
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ isExternal: false
+ name: TextToSpeechAsyncClient
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+ isExternal: false
+ name: common_billing_account_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+ isExternal: false
+ name: common_folder_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+ isExternal: false
+ name: common_location_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+ isExternal: false
+ name: common_organization_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+ isExternal: false
+ name: common_project_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+ isExternal: false
+ name: from_service_account_file
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+ isExternal: false
+ name: from_service_account_info
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+ isExternal: false
+ name: from_service_account_json
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+ isExternal: false
+ name: get_mtls_endpoint_and_cert_source
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+ isExternal: false
+ name: get_transport_class
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+ isExternal: false
+ name: list_voices
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+ isExternal: false
+ name: model_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+ isExternal: false
+ name: parse_common_billing_account_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+ isExternal: false
+ name: parse_common_folder_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+ isExternal: false
+ name: parse_common_location_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+ isExternal: false
+ name: parse_common_organization_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+ isExternal: false
+ name: parse_common_project_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+ isExternal: false
+ name: parse_model_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+ isExternal: false
+ name: synthesize_speech
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.transport
+ isExternal: false
+ name: transport
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient.transport
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.yml
new file mode 100644
index 000000000000..787ea0353a55
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.yml
@@ -0,0 +1,771 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.__exit__
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_folder_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_location_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_organization_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_project_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.list_voices
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.model_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_model_path
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.transport
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: TextToSpeechClient
+ source:
+ id: TextToSpeechClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 78
+ summary: 'Service that implements Google Cloud Text-to-Speech API.
+
+
+ '
+ syntax:
+ content: 'TextToSpeechClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Optional[typing.Union[str, google.cloud.texttospeech_v1.services.text_to_speech.transports.base.TextToSpeechTransport]]
+ = None, client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: TextToSpeechClient
+ source:
+ id: TextToSpeechClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 78
+ summary: 'Instantiates the text to speech client.
+
+ '
+ syntax:
+ content: 'TextToSpeechClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Optional[typing.Union[str, google.cloud.texttospeech_v1.services.text_to_speech.transports.base.TextToSpeechTransport]]
+ = None, client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ exceptions:
+ - description: If mutual TLS transport creation failed for any reason.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - description: The authorization credentials to attach to requests. These credentials
+ identify the application to the service; if none are specified, the client
+ will attempt to ascertain the credentials from the environment.
+ id: credentials
+ var_type: Optional[google.auth.credentials.Credentials]
+ - description: The transport to use. If set to None, a transport is chosen automatically.
+ id: transport
+ var_type: Union[str, TextToSpeechTransport]
+ - description: 'Custom options for the client. It won''t take effect if a transport
+ instance is provided. (1) The api_endpoint property can be used
+ to override the default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint: "always" (always
+ use the default mTLS endpoint), "never" (always use the default regular endpoint)
+ and "auto" (auto switch to the default mTLS endpoint if client certificate
+ is present, this is the default value). However, the api_endpoint
+ property takes precedence if provided. (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ environment variable is "true", then the client_cert_source property
+ can be used to provide client certificate for mutual TLS transport. If not
+ provided, the default SSL client certificate will be used if present. If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ is "false" or not set, no client certificate will be used.'
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ - description: The client info used to send a user-agent string along with API
+ requests. If None, then default info will be used. Generally,
+ you only need to set this if you're developing your own client library.
+ id: client_info
+ var_type: google.api_core.gapic_v1.client_info.ClientInfo
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.__exit__
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: __exit__
+ source:
+ id: __exit__
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 661
+ summary: 'Releases underlying transport''s resources.
+
+
+
+
+ Warning:
+
+ ONLY use as a context manager if the transport is NOT shared
+
+ with other clients! Exiting the with block will CLOSE the transport
+
+ and may cause errors in other clients!
+
+ '
+ syntax:
+ content: __exit__(type, value, traceback)
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.__exit__
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_billing_account_path
+ source:
+ id: common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 185
+ summary: 'Returns a fully-qualified billing_account string.
+
+
+ '
+ syntax:
+ content: 'common_billing_account_path(billing_account: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_folder_path
+ source:
+ id: common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 200
+ summary: 'Returns a fully-qualified folder string.
+
+
+ '
+ syntax:
+ content: 'common_folder_path(folder: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_location_path
+ source:
+ id: common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 245
+ summary: 'Returns a fully-qualified location string.
+
+
+ '
+ syntax:
+ content: 'common_location_path(project: str, location: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_organization_path
+ source:
+ id: common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 215
+ summary: 'Returns a fully-qualified organization string.
+
+
+ '
+ syntax:
+ content: 'common_organization_path(organization: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: common_project_path
+ source:
+ id: common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 230
+ summary: 'Returns a fully-qualified project string.
+
+
+ '
+ syntax:
+ content: 'common_project_path(project: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: from_service_account_file
+ source:
+ id: from_service_account_file
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 133
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_file(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechClient
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: from_service_account_info
+ source:
+ id: from_service_account_info
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 116
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ info.\n"
+ syntax:
+ content: 'from_service_account_info(info: dict, *args, **kwargs)'
+ parameters:
+ - description: The service account private key info.
+ id: info
+ var_type: dict
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechClient
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: from_service_account_json
+ source:
+ id: from_service_account_json
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 133
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_json(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechClient
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: get_mtls_endpoint_and_cert_source
+ source:
+ id: get_mtls_endpoint_and_cert_source
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 262
+ summary: 'Return the API endpoint and client cert source for mutual TLS.
+
+
+ The client cert source is determined in the following order:
+
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true",
+ the
+
+ client cert source is None.
+
+ (2) if `client_options.client_cert_source` is provided, use the provided one;
+ if the
+
+ default client cert source exists, use the default one; otherwise the client cert
+
+ source is None.
+
+
+ The API endpoint is determined in the following order:
+
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use
+ the
+
+ default mTLS endpoint; if the environment variabel is "never", use the default
+ API
+
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint,
+ otherwise
+
+ use the default API endpoint.
+
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ '
+ syntax:
+ content: "get_mtls_endpoint_and_cert_source(\n client_options: typing.Optional[\n\
+ \ google.api_core.client_options.ClientOptions\n ] = None,\n)"
+ exceptions:
+ - description: If any errors happen.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - defaultValue: None
+ description: Custom options for the client. Only the api_endpoint
+ and client_cert_source properties may be used in this method.
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ returns:
+ - description: returns the API endpoint and the client cert source to use.
+ var_type: Tuple[str, Callable[[], Tuple[bytes, bytes]]]
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.list_voices
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: list_voices
+ source:
+ id: list_voices
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 428
+ summary: "Returns a list of Voice supported for synthesis.\n\n```python\n# This\
+ \ snippet has been automatically generated and should be regarded as a\n# code\
+ \ template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1\n\ndef sample_list_voices():\n # Create\
+ \ a client\n client = texttospeech_v1.TextToSpeechClient()\n\n # Initialize\
+ \ request argument(s)\n request = texttospeech_v1.ListVoicesRequest(\n )\n\
+ \n # Make the request\n response = client.list_voices(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "list_voices(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1.types.cloud_tts.ListVoicesRequest,\
+ \ dict\n ]\n ] = None,\n *,\n language_code: typing.Optional[str]\
+ \ = None,\n retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.texttospeech_v1.types.cloud_tts.ListVoicesResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the ListVoices method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1.types.ListVoicesRequest ,
+ dict]
+ - description: Optional. Recommended. BCP-47 __
+ language tag. If not specified, the API will return all supported voices.
+ If specified, the ListVoices call will only return voices that can be used
+ to synthesize this language_code. For example, if you specify "en-NZ",
+ all "en-NZ" voices will be returned. If you specify "no",
+ both "no-\*" (Norwegian) and "nb-\*" (Norwegian
+ Bokmal) voices will be returned. This corresponds to the language_code
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: language_code
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the ListVoices method.
+ var_type: google.cloud.texttospeech_v1.types.ListVoicesResponse
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.list_voices
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: model_path
+ source:
+ id: model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 163
+ summary: 'Returns a fully-qualified model string.
+
+
+ '
+ syntax:
+ content: 'model_path(project: str, location: str, model: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_billing_account_path
+ source:
+ id: parse_common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 194
+ summary: 'Parse a billing_account path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_billing_account_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_folder_path
+ source:
+ id: parse_common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 209
+ summary: 'Parse a folder path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_folder_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_location_path
+ source:
+ id: parse_common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 256
+ summary: 'Parse a location path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_location_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_organization_path
+ source:
+ id: parse_common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 224
+ summary: 'Parse a organization path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_organization_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_common_project_path
+ source:
+ id: parse_common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 239
+ summary: 'Parse a project path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_project_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: parse_model_path
+ source:
+ id: parse_model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 176
+ summary: 'Parses a model path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_model_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: synthesize_speech
+ source:
+ id: synthesize_speech
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/client.py
+ startLine: 530
+ summary: "Synthesizes speech synchronously: receive results\nafter all text input\
+ \ has been processed.\n\n```python\n# This snippet has been automatically generated\
+ \ and should be regarded as a\n# code template only.\n# It will require modifications\
+ \ to work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1\n\ndef sample_synthesize_speech():\n\
+ \ # Create a client\n client = texttospeech_v1.TextToSpeechClient()\n\n\
+ \ # Initialize request argument(s)\n input = texttospeech_v1.SynthesisInput()\n\
+ \ input.text = \"text_value\"\n\n voice = texttospeech_v1.VoiceSelectionParams()\n\
+ \ voice.language_code = \"language_code_value\"\n\n audio_config = texttospeech_v1.AudioConfig()\n\
+ \ audio_config.audio_encoding = \"ALAW\"\n\n request = texttospeech_v1.SynthesizeSpeechRequest(\n\
+ \ input=input,\n voice=voice,\n audio_config=audio_config,\n\
+ \ )\n\n # Make the request\n response = client.synthesize_speech(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "synthesize_speech(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1.types.cloud_tts.SynthesizeSpeechRequest,\
+ \ dict\n ]\n ] = None,\n *,\n input: typing.Optional[\n \
+ \ google.cloud.texttospeech_v1.types.cloud_tts.SynthesisInput\n ] = None,\n\
+ \ voice: typing.Optional[\n google.cloud.texttospeech_v1.types.cloud_tts.VoiceSelectionParams\n\
+ \ ] = None,\n audio_config: typing.Optional[\n google.cloud.texttospeech_v1.types.cloud_tts.AudioConfig\n\
+ \ ] = None,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.cloud.texttospeech_v1.types.cloud_tts.SynthesizeSpeechResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the SynthesizeSpeech method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest ,
+ dict]
+ - description: Required. The Synthesizer requires either plain text or SSML as
+ input. This corresponds to the input field on the request
+ instance; if request is provided, this should not be set.
+ id: input
+ var_type: google.cloud.texttospeech_v1.types.SynthesisInput
+ - description: Required. The desired voice of the synthesized audio. This corresponds
+ to the voice field on the request instance; if request
+ is provided, this should not be set.
+ id: voice
+ var_type: google.cloud.texttospeech_v1.types.VoiceSelectionParams
+ - description: Required. The configuration of the synthesized audio. This corresponds
+ to the audio_config field on the request instance;
+ if request is provided, this should not be set.
+ id: audio_config
+ var_type: google.cloud.texttospeech_v1.types.AudioConfig
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the SynthesizeSpeech method.
+ var_type: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+ type: method
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+- &id001
+ attributes: []
+ class: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.transport
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: transport
+ source:
+ id: transport
+ path: null
+ startLine: null
+ summary: 'Returns the transport used by the client instance.
+
+ '
+ syntax:
+ returns:
+ - description: The transport used by the client instance.
+ var_type: TextToSpeechTransport
+ type: property
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.transport
+- *id001
+references:
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ isExternal: false
+ name: TextToSpeechClient
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.__exit__
+ isExternal: false
+ name: __exit__
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.__exit__
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+ isExternal: false
+ name: common_billing_account_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_folder_path
+ isExternal: false
+ name: common_folder_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_folder_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_location_path
+ isExternal: false
+ name: common_location_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_location_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_organization_path
+ isExternal: false
+ name: common_organization_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_organization_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_project_path
+ isExternal: false
+ name: common_project_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.common_project_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+ isExternal: false
+ name: from_service_account_file
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+ isExternal: false
+ name: from_service_account_info
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+ isExternal: false
+ name: from_service_account_json
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+ isExternal: false
+ name: get_mtls_endpoint_and_cert_source
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.list_voices
+ isExternal: false
+ name: list_voices
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.list_voices
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.model_path
+ isExternal: false
+ name: model_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.model_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+ isExternal: false
+ name: parse_common_billing_account_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+ isExternal: false
+ name: parse_common_folder_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+ isExternal: false
+ name: parse_common_location_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+ isExternal: false
+ name: parse_common_organization_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+ isExternal: false
+ name: parse_common_project_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_model_path
+ isExternal: false
+ name: parse_model_path
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.parse_model_path
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+ isExternal: false
+ name: synthesize_speech
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.transport
+ isExternal: false
+ name: transport
+ parent: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient.transport
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.yml
new file mode 100644
index 000000000000..326e773c2625
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.services.text_to_speech.yml
@@ -0,0 +1,30 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ - google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1.services.text_to_speech
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.services.text_to_speech
+ name: text_to_speech
+ source:
+ id: text_to_speech
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/services/text_to_speech/__init__.py
+ startLine: 0
+ summary: API documentation for `texttospeech_v1.services.text_to_speech` package.
+ syntax: {}
+ type: subPackage
+ uid: google.cloud.texttospeech_v1.services.text_to_speech
+references:
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ isExternal: false
+ name: TextToSpeechAsyncClient
+ parent: google.cloud.texttospeech_v1.services.text_to_speech
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+- fullName: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ isExternal: false
+ name: TextToSpeechClient
+ parent: google.cloud.texttospeech_v1.services.text_to_speech
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.AudioConfig.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.AudioConfig.yml
new file mode 100644
index 000000000000..d050b11e9b4b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.AudioConfig.yml
@@ -0,0 +1,65 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The format of the audio byte\n stream."
+ id: audio_encoding
+ var_type: google.cloud.texttospeech_v1.types.AudioEncoding
+ - description: "Optional. Input only. Speaking rate/speed, in the range\n [0.25,\
+ \ 4.0]. 1.0 is the normal native speed supported by the\n specific voice.\
+ \ 2.0 is twice as fast, and 0.5 is half as\n fast. If unset(0.0), defaults\
+ \ to the native 1.0 speed. Any\n other values < 0.25 or > 4.0 will return\
+ \ an error."
+ id: speaking_rate
+ var_type: float
+ - description: "Optional. Input only. Speaking pitch, in the range [-20.0,\n 20.0].\
+ \ 20 means increase 20 semitones from the original\n pitch. -20 means decrease\
+ \ 20 semitones from the original\n pitch."
+ id: pitch
+ var_type: float
+ - description: "Optional. Input only. Volume gain (in dB) of the normal\n native\
+ \ volume supported by the specific voice, in the range\n [-96.0, 16.0]. If\
+ \ unset, or set to a value of 0.0 (dB), will\n play at normal native signal\
+ \ amplitude. A value of -6.0 (dB)\n will play at approximately half the amplitude\
+ \ of the normal\n native signal amplitude. A value of +6.0 (dB) will play\
+ \ at\n approximately twice the amplitude of the normal native\n signal amplitude.\
+ \ Strongly recommend not to exceed +10 (dB)\n as there's usually no effective\
+ \ increase in loudness for any\n value greater than that."
+ id: volume_gain_db
+ var_type: float
+ - description: "Optional. The synthesis sample rate (in hertz) for this\n audio.\
+ \ When this is specified in SynthesizeSpeechRequest, if\n this is different\
+ \ from the voice's natural sample rate, then\n the synthesizer will honor\
+ \ this request by converting to the\n desired sample rate (which might result\
+ \ in worse audio\n quality), unless the specified sample rate is not supported\n\
+ \ for the encoding chosen, in which case it will fail the\n request and\
+ \ return [google.rpc.Code.INVALID_ARGUMENT][]."
+ id: sample_rate_hertz
+ var_type: int
+ - description: "Optional. Input only. An identifier which selects 'audio\n effects'\
+ \ profiles that are applied on (post synthesized)\n text to speech. Effects\
+ \ are applied on top of each other in\n the order they are given. See `audio\n\
+ \ profiles `__\n\
+ \ for current supported profile ids."
+ id: effects_profile_id
+ var_type: Sequence[str]
+ children: []
+ class: google.cloud.texttospeech_v1.types.AudioConfig
+ fullName: google.cloud.texttospeech_v1.types.AudioConfig
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: AudioConfig
+ source:
+ id: AudioConfig
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 262
+ summary: 'Description of audio data to be synthesized.
+
+ '
+ syntax:
+ content: AudioConfig(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.AudioConfig
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.AudioEncoding.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.AudioEncoding.yml
new file mode 100644
index 000000000000..a5930a8f0279
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.AudioEncoding.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.texttospeech_v1.types.AudioEncoding
+ fullName: google.cloud.texttospeech_v1.types.AudioEncoding
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: AudioEncoding
+ source:
+ id: AudioEncoding
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 46
+ summary: 'Configuration to set up audio encoder. The encoding
+
+ determines the output audio format that we''d like.
+
+
+ '
+ syntax:
+ content: AudioEncoding(value)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.AudioEncoding
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage.yml
new file mode 100644
index 000000000000..9828a1b4a980
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage.yml
@@ -0,0 +1,29 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
+ fullName: google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ name: ReportedUsage
+ source:
+ id: ReportedUsage
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 348
+ summary: 'The usage of the synthesized audio. You must report your
+
+ honest and correct usage of the service as it''s regulated by
+
+ contract and will cause significant difference in billing.
+
+
+ '
+ syntax:
+ content: ReportedUsage(value)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.CustomVoiceParams.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.CustomVoiceParams.yml
new file mode 100644
index 000000000000..b191aa1b2a3c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.CustomVoiceParams.yml
@@ -0,0 +1,37 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the AutoML model that\n synthesizes the\
+ \ custom voice."
+ id: model
+ var_type: str
+ - description: "Optional. The usage of the synthesized audio\n to be reported."
+ id: reported_usage
+ var_type: google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
+ children:
+ - google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
+ class: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ fullName: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: CustomVoiceParams
+ source:
+ id: CustomVoiceParams
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 336
+ summary: 'Description of the custom voice to be synthesized.
+
+ '
+ syntax:
+ content: CustomVoiceParams(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.CustomVoiceParams
+references:
+- fullName: google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
+ isExternal: false
+ name: ReportedUsage
+ parent: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ uid: google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.ListVoicesRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.ListVoicesRequest.yml
new file mode 100644
index 000000000000..17086411141d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.ListVoicesRequest.yml
@@ -0,0 +1,35 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Optional. Recommended.\n BCP-47 __\n\
+ \ language tag. If not specified, the API will return all\n supported voices.\
+ \ If specified, the ListVoices call will\n only return voices that can be\
+ \ used to synthesize this\n language_code. For example, if you specify \"\
+ en-NZ\", all\n \"en-NZ\" voices will be returned. If you\
+ \ specify\n \"no\", both \"no-\\*\" (Norwegian)\
+ \ and \"nb-\\*\"\n (Norwegian Bokmal) voices will be returned."
+ id: language_code
+ var_type: str
+ children: []
+ class: google.cloud.texttospeech_v1.types.ListVoicesRequest
+ fullName: google.cloud.texttospeech_v1.types.ListVoicesRequest
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: ListVoicesRequest
+ source:
+ id: ListVoicesRequest
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 58
+ summary: 'The top-level message sent by the client for the `ListVoices`
+
+ method.
+
+ '
+ syntax:
+ content: ListVoicesRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.ListVoicesRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.ListVoicesResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.ListVoicesResponse.yml
new file mode 100644
index 000000000000..1deede89c1b2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.ListVoicesResponse.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: The list of voices.
+ id: voices
+ var_type: Sequence[google.cloud.texttospeech_v1.types.Voice ]
+ children: []
+ class: google.cloud.texttospeech_v1.types.ListVoicesResponse
+ fullName: google.cloud.texttospeech_v1.types.ListVoicesResponse
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: ListVoicesResponse
+ source:
+ id: ListVoicesResponse
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 81
+ summary: 'The message returned to the client by the `ListVoices` method.
+
+ '
+ syntax:
+ content: ListVoicesResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.ListVoicesResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SsmlVoiceGender.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SsmlVoiceGender.yml
new file mode 100644
index 000000000000..ad4dc5d1a278
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SsmlVoiceGender.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+ fullName: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: SsmlVoiceGender
+ source:
+ id: SsmlVoiceGender
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 36
+ summary: 'Gender of the voice as described in `SSML voice
+
+ element `__.
+
+
+ '
+ syntax:
+ content: SsmlVoiceGender(value)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesisInput.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesisInput.yml
new file mode 100644
index 000000000000..79dd029cc71e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesisInput.yml
@@ -0,0 +1,52 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The raw text to be synthesized.\n \n This field is a member\
+ \ of oneof_ input_source."
+ id: text
+ var_type: str
+ - description: "The SSML document to be synthesized. The SSML document must\n \
+ \ be valid and well-formed. Otherwise the RPC will fail and\n return [google.rpc.Code.INVALID_ARGUMENT][].\
+ \ For more\n information, see\n SSML __.\n\
+ \ \n This field is a member of oneof_ input_source."
+ id: ssml
+ var_type: str
+ children: []
+ class: google.cloud.texttospeech_v1.types.SynthesisInput
+ fullName: google.cloud.texttospeech_v1.types.SynthesisInput
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: SynthesisInput
+ source:
+ id: SynthesisInput
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 166
+ summary: 'Contains text input to be synthesized. Either `text` or `ssml`
+
+ must be supplied. Supplying both or neither returns
+
+ [google.rpc.Code.INVALID_ARGUMENT][]. The input size is limited to
+
+ 5000 characters.
+
+
+ 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
+
+ '
+ syntax:
+ content: SynthesisInput(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.SynthesisInput
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest.yml
new file mode 100644
index 000000000000..c6cd5b673d7a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest.yml
@@ -0,0 +1,37 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The Synthesizer requires either\n plain text or SSML\
+ \ as input."
+ id: input
+ var_type: google.cloud.texttospeech_v1.types.SynthesisInput
+ - description: "Required. The desired voice of the\n synthesized audio."
+ id: voice
+ var_type: google.cloud.texttospeech_v1.types.VoiceSelectionParams
+ - description: "Required. The configuration of the\n synthesized audio."
+ id: audio_config
+ var_type: google.cloud.texttospeech_v1.types.AudioConfig
+ children: []
+ class: google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest
+ fullName: google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: SynthesizeSpeechRequest
+ source:
+ id: SynthesizeSpeechRequest
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 133
+ summary: 'The top-level message sent by the client for the
+
+ `SynthesizeSpeech` method.
+
+ '
+ syntax:
+ content: SynthesizeSpeechRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse.yml
new file mode 100644
index 000000000000..d63e4cec5a9c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse.yml
@@ -0,0 +1,34 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The audio data bytes encoded as specified in the request,\n including\
+ \ the header for encodings that are wrapped in\n containers (e.g. MP3, OGG_OPUS).\
+ \ For LINEAR16 audio, we\n include the WAV header. Note: as with all bytes\
+ \ fields,\n protobuffers use a pure binary representation, whereas JSON\n\
+ \ representations use base64."
+ id: audio_content
+ var_type: bytes
+ children: []
+ class: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+ fullName: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: SynthesizeSpeechResponse
+ source:
+ id: SynthesizeSpeechResponse
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 368
+ summary: 'The message returned to the client by the `SynthesizeSpeech`
+
+ method.
+
+ '
+ syntax:
+ content: SynthesizeSpeechResponse(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.Voice.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.Voice.yml
new file mode 100644
index 000000000000..9513dcc71db8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.Voice.yml
@@ -0,0 +1,38 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The languages that this voice supports, expressed as\n BCP-47\
+ \ __\n language tags\
+ \ (e.g. \"en-US\", \"es-419\", \"cmn-tw\")."
+ id: language_codes
+ var_type: Sequence[str]
+ - description: "The name of this voice. Each distinct voice\n has a unique name."
+ id: name
+ var_type: str
+ - description: The gender of this voice.
+ id: ssml_gender
+ var_type: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+ - description: "The natural sample rate (in hertz) for this\n voice."
+ id: natural_sample_rate_hertz
+ var_type: int
+ children: []
+ class: google.cloud.texttospeech_v1.types.Voice
+ fullName: google.cloud.texttospeech_v1.types.Voice
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: Voice
+ source:
+ id: Voice
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 96
+ summary: 'Description of a voice supported by the TTS service.
+
+ '
+ syntax:
+ content: Voice(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.Voice
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.VoiceSelectionParams.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.VoiceSelectionParams.yml
new file mode 100644
index 000000000000..e979cd85a1eb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.VoiceSelectionParams.yml
@@ -0,0 +1,53 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The language (and potentially also the region) of\n \
+ \ the voice expressed as a\n BCP-47 __\n\
+ \ language tag, e.g. \"en-US\". This should not include a script\n tag (e.g.\
+ \ use \"cmn-cn\" rather than \"cmn-Hant-cn\"), because\n the script will be\
+ \ inferred from the input provided in the\n SynthesisInput. The TTS service\
+ \ will use this parameter to\n help choose an appropriate voice. Note that\
+ \ the TTS service\n may choose a voice with a slightly different language\
+ \ code\n than the one selected; it may substitute a different region\n (e.g.\
+ \ using en-US rather than en-CA if there isn't a\n Canadian voice available),\
+ \ or even a different language,\n e.g. using \"nb\" (Norwegian Bokmal) instead\
+ \ of \"no\"\n (Norwegian)\"."
+ id: language_code
+ var_type: str
+ - description: "The name of the voice. If not set, the service will choose a\n \
+ \ voice based on the other parameters such as language_code\n and gender."
+ id: name
+ var_type: str
+ - description: "The preferred gender of the voice. If not set, the service\n will\
+ \ choose a voice based on the other parameters such as\n language_code and\
+ \ name. Note that this is only a preference,\n not requirement; if a voice\
+ \ of the appropriate gender is not\n available, the synthesizer should substitute\
+ \ a voice with a\n different gender rather than failing the request."
+ id: ssml_gender
+ var_type: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+ - description: "The configuration for a custom voice. If\n [CustomVoiceParams.model]\
+ \ is set, the service will choose\n the custom voice matching the specified\
+ \ configuration."
+ id: custom_voice
+ var_type: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ children: []
+ class: google.cloud.texttospeech_v1.types.VoiceSelectionParams
+ fullName: google.cloud.texttospeech_v1.types.VoiceSelectionParams
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: VoiceSelectionParams
+ source:
+ id: VoiceSelectionParams
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/cloud_tts.py
+ startLine: 206
+ summary: 'Description of which voice to use for a synthesis request.
+
+ '
+ syntax:
+ content: VoiceSelectionParams(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1.types.VoiceSelectionParams
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.yml
new file mode 100644
index 000000000000..6ad4b9384b79
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1.types.yml
@@ -0,0 +1,84 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.texttospeech_v1.types.AudioConfig
+ - google.cloud.texttospeech_v1.types.AudioEncoding
+ - google.cloud.texttospeech_v1.types.CustomVoiceParams
+ - google.cloud.texttospeech_v1.types.ListVoicesRequest
+ - google.cloud.texttospeech_v1.types.ListVoicesResponse
+ - google.cloud.texttospeech_v1.types.SsmlVoiceGender
+ - google.cloud.texttospeech_v1.types.SynthesisInput
+ - google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest
+ - google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+ - google.cloud.texttospeech_v1.types.Voice
+ - google.cloud.texttospeech_v1.types.VoiceSelectionParams
+ fullName: google.cloud.texttospeech_v1.types
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1.types
+ name: types
+ source:
+ id: types
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1/types/__init__.py
+ startLine: 0
+ summary: API documentation for `texttospeech_v1.types` package.
+ syntax: {}
+ type: subPackage
+ uid: google.cloud.texttospeech_v1.types
+references:
+- fullName: google.cloud.texttospeech_v1.types.AudioConfig
+ isExternal: false
+ name: AudioConfig
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.AudioConfig
+- fullName: google.cloud.texttospeech_v1.types.AudioEncoding
+ isExternal: false
+ name: AudioEncoding
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.AudioEncoding
+- fullName: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ isExternal: false
+ name: CustomVoiceParams
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.CustomVoiceParams
+- fullName: google.cloud.texttospeech_v1.types.ListVoicesRequest
+ isExternal: false
+ name: ListVoicesRequest
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.ListVoicesRequest
+- fullName: google.cloud.texttospeech_v1.types.ListVoicesResponse
+ isExternal: false
+ name: ListVoicesResponse
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.ListVoicesResponse
+- fullName: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+ isExternal: false
+ name: SsmlVoiceGender
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+- fullName: google.cloud.texttospeech_v1.types.SynthesisInput
+ isExternal: false
+ name: SynthesisInput
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.SynthesisInput
+- fullName: google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest
+ isExternal: false
+ name: SynthesizeSpeechRequest
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest
+- fullName: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+ isExternal: false
+ name: SynthesizeSpeechResponse
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+- fullName: google.cloud.texttospeech_v1.types.Voice
+ isExternal: false
+ name: Voice
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.Voice
+- fullName: google.cloud.texttospeech_v1.types.VoiceSelectionParams
+ isExternal: false
+ name: VoiceSelectionParams
+ parent: google.cloud.texttospeech_v1.types
+ uid: google.cloud.texttospeech_v1.types.VoiceSelectionParams
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.yml
new file mode 100644
index 000000000000..9957cac1183a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.yml
@@ -0,0 +1,761 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.transport
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: TextToSpeechAsyncClient
+ source:
+ id: TextToSpeechAsyncClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 41
+ summary: 'Service that implements Google Cloud Text-to-Speech API.
+
+
+ '
+ syntax:
+ content: 'TextToSpeechAsyncClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Union[str, google.cloud.texttospeech_v1beta1.services.text_to_speech.transports.base.TextToSpeechTransport]
+ = ''grpc_asyncio'', client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: TextToSpeechAsyncClient
+ source:
+ id: TextToSpeechAsyncClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 41
+ summary: 'Instantiates the text to speech client.
+
+ '
+ syntax:
+ content: 'TextToSpeechAsyncClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Union[str, google.cloud.texttospeech_v1beta1.services.text_to_speech.transports.base.TextToSpeechTransport]
+ = ''grpc_asyncio'', client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ exceptions:
+ - description: If mutual TLS transport creation failed for any reason.
+ var_type: google.auth.exceptions.MutualTlsChannelError
+ parameters:
+ - description: The authorization credentials to attach to requests. These credentials
+ identify the application to the service; if none are specified, the client
+ will attempt to ascertain the credentials from the environment.
+ id: credentials
+ var_type: Optional[google.auth.credentials.Credentials]
+ - description: The transport to use. If set to None, a transport is chosen automatically.
+ id: transport
+ var_type: Union[str, .TextToSpeechTransport]
+ - description: 'Custom options for the client. It won''t take effect if a transport
+ instance is provided. (1) The api_endpoint property can be used
+ to override the default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint: "always" (always
+ use the default mTLS endpoint), "never" (always use the default regular endpoint)
+ and "auto" (auto switch to the default mTLS endpoint if client certificate
+ is present, this is the default value). However, the api_endpoint
+ property takes precedence if provided. (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ environment variable is "true", then the client_cert_source property
+ can be used to provide client certificate for mutual TLS transport. If not
+ provided, the default SSL client certificate will be used if present. If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ is "false" or not set, no client certificate will be used.'
+ id: client_options
+ var_type: ClientOptions
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_billing_account_path
+ source:
+ id: common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 185
+ summary: 'Returns a fully-qualified billing_account string.
+
+
+ '
+ syntax:
+ content: 'common_billing_account_path(billing_account: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_folder_path
+ source:
+ id: common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 200
+ summary: 'Returns a fully-qualified folder string.
+
+
+ '
+ syntax:
+ content: 'common_folder_path(folder: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_location_path
+ source:
+ id: common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 245
+ summary: 'Returns a fully-qualified location string.
+
+
+ '
+ syntax:
+ content: 'common_location_path(project: str, location: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_organization_path
+ source:
+ id: common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 215
+ summary: 'Returns a fully-qualified organization string.
+
+
+ '
+ syntax:
+ content: 'common_organization_path(organization: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_project_path
+ source:
+ id: common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 230
+ summary: 'Returns a fully-qualified project string.
+
+
+ '
+ syntax:
+ content: 'common_project_path(project: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: from_service_account_file
+ source:
+ id: from_service_account_file
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 87
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_file(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechAsyncClient
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: from_service_account_info
+ source:
+ id: from_service_account_info
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 72
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ info.\n"
+ syntax:
+ content: 'from_service_account_info(info: dict, *args, **kwargs)'
+ parameters:
+ - description: The service account private key info.
+ id: info
+ var_type: dict
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechAsyncClient
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: from_service_account_json
+ source:
+ id: from_service_account_json
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 87
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_json(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechAsyncClient
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: get_mtls_endpoint_and_cert_source
+ source:
+ id: get_mtls_endpoint_and_cert_source
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 105
+ summary: 'Return the API endpoint and client cert source for mutual TLS.
+
+
+ The client cert source is determined in the following order:
+
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true",
+ the
+
+ client cert source is None.
+
+ (2) if `client_options.client_cert_source` is provided, use the provided one;
+ if the
+
+ default client cert source exists, use the default one; otherwise the client cert
+
+ source is None.
+
+
+ The API endpoint is determined in the following order:
+
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use
+ the
+
+ default mTLS endpoint; if the environment variabel is "never", use the default
+ API
+
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint,
+ otherwise
+
+ use the default API endpoint.
+
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ '
+ syntax:
+ content: "get_mtls_endpoint_and_cert_source(\n client_options: typing.Optional[\n\
+ \ google.api_core.client_options.ClientOptions\n ] = None,\n)"
+ exceptions:
+ - description: If any errors happen.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - defaultValue: None
+ description: Custom options for the client. Only the api_endpoint
+ and client_cert_source properties may be used in this method.
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ returns:
+ - description: returns the API endpoint and the client cert source to use.
+ var_type: Tuple[str, Callable[[], Tuple[bytes, bytes]]]
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: get_transport_class
+ source:
+ id: get_transport_class
+ path: null
+ startLine: null
+ summary: 'Returns an appropriate transport class.
+
+ '
+ syntax:
+ content: "get_transport_class() -> typing.Type[\n google.cloud.texttospeech_v1beta1.services.text_to_speech.transports.base.TextToSpeechTransport\n\
+ ]"
+ parameters:
+ - defaultValue: None
+ description: The name of the desired transport. If none is provided, then the
+ first transport in the registry is used.
+ id: label
+ var_type: str
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: list_voices
+ source:
+ id: list_voices
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 201
+ summary: "Returns a list of Voice supported for synthesis.\n\n```python\n# This\
+ \ snippet has been automatically generated and should be regarded as a\n# code\
+ \ template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1beta1\n\nasync def sample_list_voices():\n\
+ \ # Create a client\n client = texttospeech_v1beta1.TextToSpeechAsyncClient()\n\
+ \n # Initialize request argument(s)\n request = texttospeech_v1beta1.ListVoicesRequest(\n\
+ \ )\n\n # Make the request\n response = await client.list_voices(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "list_voices(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.ListVoicesRequest,\
+ \ dict\n ]\n ] = None,\n *,\n language_code: typing.Optional[str]\
+ \ = None,\n retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.ListVoicesResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the ListVoices method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1beta1.types.ListVoicesRequest ,
+ dict]
+ - description: Optional. Recommended. BCP-47 __
+ language tag. If not specified, the API will return all supported voices.
+ If specified, the ListVoices call will only return voices that can be used
+ to synthesize this language_code. For example, if you specify "en-NZ",
+ all "en-NZ" voices will be returned. If you specify "no",
+ both "no-\*" (Norwegian) and "nb-\*" (Norwegian
+ Bokmal) voices will be returned. This corresponds to the language_code
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: language_code
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the ListVoices method.
+ var_type: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: model_path
+ source:
+ id: model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 163
+ summary: 'Returns a fully-qualified model string.
+
+
+ '
+ syntax:
+ content: 'model_path(project: str, location: str, model: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_billing_account_path
+ source:
+ id: parse_common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 194
+ summary: 'Parse a billing_account path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_billing_account_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_folder_path
+ source:
+ id: parse_common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 209
+ summary: 'Parse a folder path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_folder_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_location_path
+ source:
+ id: parse_common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 256
+ summary: 'Parse a location path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_location_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_organization_path
+ source:
+ id: parse_common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 224
+ summary: 'Parse a organization path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_organization_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_project_path
+ source:
+ id: parse_common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 239
+ summary: 'Parse a project path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_project_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_model_path
+ source:
+ id: parse_model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 176
+ summary: 'Parses a model path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_model_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: synthesize_speech
+ source:
+ id: synthesize_speech
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/async_client.py
+ startLine: 303
+ summary: "Synthesizes speech synchronously: receive results\nafter all text input\
+ \ has been processed.\n\n```python\n# This snippet has been automatically generated\
+ \ and should be regarded as a\n# code template only.\n# It will require modifications\
+ \ to work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1beta1\n\nasync def sample_synthesize_speech():\n\
+ \ # Create a client\n client = texttospeech_v1beta1.TextToSpeechAsyncClient()\n\
+ \n # Initialize request argument(s)\n input = texttospeech_v1beta1.SynthesisInput()\n\
+ \ input.text = \"text_value\"\n\n voice = texttospeech_v1beta1.VoiceSelectionParams()\n\
+ \ voice.language_code = \"language_code_value\"\n\n audio_config = texttospeech_v1beta1.AudioConfig()\n\
+ \ audio_config.audio_encoding = \"ALAW\"\n\n request = texttospeech_v1beta1.SynthesizeSpeechRequest(\n\
+ \ input=input,\n voice=voice,\n audio_config=audio_config,\n\
+ \ )\n\n # Make the request\n response = await client.synthesize_speech(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "synthesize_speech(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.SynthesizeSpeechRequest,\n\
+ \ dict,\n ]\n ] = None,\n *,\n input: typing.Optional[\n\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.SynthesisInput\n\
+ \ ] = None,\n voice: typing.Optional[\n google.cloud.texttospeech_v1beta1.types.cloud_tts.VoiceSelectionParams\n\
+ \ ] = None,\n audio_config: typing.Optional[\n google.cloud.texttospeech_v1beta1.types.cloud_tts.AudioConfig\n\
+ \ ] = None,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.cloud.texttospeech_v1beta1.types.cloud_tts.SynthesizeSpeechResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the SynthesizeSpeech method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest ,
+ dict]
+ - description: Required. The Synthesizer requires either plain text or SSML as
+ input. This corresponds to the input field on the request
+ instance; if request is provided, this should not be set.
+ id: input
+ var_type: SynthesisInput
+ - description: Required. The desired voice of the synthesized audio. This corresponds
+ to the voice field on the request instance; if request
+ is provided, this should not be set.
+ id: voice
+ var_type: VoiceSelectionParams
+ - description: Required. The configuration of the synthesized audio. This corresponds
+ to the audio_config field on the request instance;
+ if request is provided, this should not be set.
+ id: audio_config
+ var_type: AudioConfig
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the SynthesizeSpeech method.
+ var_type: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+- &id001
+ attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.transport
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: transport
+ source:
+ id: transport
+ path: null
+ startLine: null
+ summary: 'Returns the transport used by the client instance.
+
+ '
+ syntax:
+ returns:
+ - description: The transport used by the client instance.
+ var_type: TextToSpeechTransport
+ type: property
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.transport
+- *id001
+references:
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ isExternal: false
+ name: TextToSpeechAsyncClient
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+ isExternal: false
+ name: common_billing_account_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_billing_account_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+ isExternal: false
+ name: common_folder_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_folder_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+ isExternal: false
+ name: common_location_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_location_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+ isExternal: false
+ name: common_organization_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_organization_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+ isExternal: false
+ name: common_project_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.common_project_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+ isExternal: false
+ name: from_service_account_file
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_file
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+ isExternal: false
+ name: from_service_account_info
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_info
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+ isExternal: false
+ name: from_service_account_json
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.from_service_account_json
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+ isExternal: false
+ name: get_mtls_endpoint_and_cert_source
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_mtls_endpoint_and_cert_source
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+ isExternal: false
+ name: get_transport_class
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.get_transport_class
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+ isExternal: false
+ name: list_voices
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.list_voices
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+ isExternal: false
+ name: model_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.model_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+ isExternal: false
+ name: parse_common_billing_account_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_billing_account_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+ isExternal: false
+ name: parse_common_folder_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_folder_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+ isExternal: false
+ name: parse_common_location_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_location_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+ isExternal: false
+ name: parse_common_organization_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_organization_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+ isExternal: false
+ name: parse_common_project_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_common_project_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+ isExternal: false
+ name: parse_model_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.parse_model_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+ isExternal: false
+ name: synthesize_speech
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.synthesize_speech
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.transport
+ isExternal: false
+ name: transport
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient.transport
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.yml
new file mode 100644
index 000000000000..1ebc975862be
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.yml
@@ -0,0 +1,771 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.__exit__
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_folder_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_location_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_organization_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_project_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.list_voices
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.model_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_model_path
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.transport
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: TextToSpeechClient
+ source:
+ id: TextToSpeechClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 78
+ summary: 'Service that implements Google Cloud Text-to-Speech API.
+
+
+ '
+ syntax:
+ content: 'TextToSpeechClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Optional[typing.Union[str, google.cloud.texttospeech_v1beta1.services.text_to_speech.transports.base.TextToSpeechTransport]]
+ = None, client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: TextToSpeechClient
+ source:
+ id: TextToSpeechClient
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 78
+ summary: 'Instantiates the text to speech client.
+
+ '
+ syntax:
+ content: 'TextToSpeechClient(*, credentials: typing.Optional[google.auth.credentials.Credentials]
+ = None, transport: typing.Optional[typing.Union[str, google.cloud.texttospeech_v1beta1.services.text_to_speech.transports.base.TextToSpeechTransport]]
+ = None, client_options: typing.Optional[google.api_core.client_options.ClientOptions]
+ = None, client_info: google.api_core.gapic_v1.client_info.ClientInfo = )'
+ exceptions:
+ - description: If mutual TLS transport creation failed for any reason.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - description: The authorization credentials to attach to requests. These credentials
+ identify the application to the service; if none are specified, the client
+ will attempt to ascertain the credentials from the environment.
+ id: credentials
+ var_type: Optional[google.auth.credentials.Credentials]
+ - description: The transport to use. If set to None, a transport is chosen automatically.
+ id: transport
+ var_type: Union[str, TextToSpeechTransport]
+ - description: 'Custom options for the client. It won''t take effect if a transport
+ instance is provided. (1) The api_endpoint property can be used
+ to override the default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint: "always" (always
+ use the default mTLS endpoint), "never" (always use the default regular endpoint)
+ and "auto" (auto switch to the default mTLS endpoint if client certificate
+ is present, this is the default value). However, the api_endpoint
+ property takes precedence if provided. (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ environment variable is "true", then the client_cert_source property
+ can be used to provide client certificate for mutual TLS transport. If not
+ provided, the default SSL client certificate will be used if present. If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ is "false" or not set, no client certificate will be used.'
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ - description: The client info used to send a user-agent string along with API
+ requests. If None, then default info will be used. Generally,
+ you only need to set this if you're developing your own client library.
+ id: client_info
+ var_type: google.api_core.gapic_v1.client_info.ClientInfo
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.__exit__
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: __exit__
+ source:
+ id: __exit__
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 661
+ summary: 'Releases underlying transport''s resources.
+
+
+
+
+ Warning:
+
+ ONLY use as a context manager if the transport is NOT shared
+
+ with other clients! Exiting the with block will CLOSE the transport
+
+ and may cause errors in other clients!
+
+ '
+ syntax:
+ content: __exit__(type, value, traceback)
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.__exit__
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_billing_account_path
+ source:
+ id: common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 185
+ summary: 'Returns a fully-qualified billing_account string.
+
+
+ '
+ syntax:
+ content: 'common_billing_account_path(billing_account: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_folder_path
+ source:
+ id: common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 200
+ summary: 'Returns a fully-qualified folder string.
+
+
+ '
+ syntax:
+ content: 'common_folder_path(folder: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_location_path
+ source:
+ id: common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 245
+ summary: 'Returns a fully-qualified location string.
+
+
+ '
+ syntax:
+ content: 'common_location_path(project: str, location: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_organization_path
+ source:
+ id: common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 215
+ summary: 'Returns a fully-qualified organization string.
+
+
+ '
+ syntax:
+ content: 'common_organization_path(organization: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: common_project_path
+ source:
+ id: common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 230
+ summary: 'Returns a fully-qualified project string.
+
+
+ '
+ syntax:
+ content: 'common_project_path(project: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: from_service_account_file
+ source:
+ id: from_service_account_file
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 133
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_file(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechClient
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: from_service_account_info
+ source:
+ id: from_service_account_info
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 116
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ info.\n"
+ syntax:
+ content: 'from_service_account_info(info: dict, *args, **kwargs)'
+ parameters:
+ - description: The service account private key info.
+ id: info
+ var_type: dict
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechClient
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: from_service_account_json
+ source:
+ id: from_service_account_json
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 133
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ file.\n"
+ syntax:
+ content: 'from_service_account_json(filename: str, *args, **kwargs)'
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ returns:
+ - description: The constructed client.
+ var_type: TextToSpeechClient
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: get_mtls_endpoint_and_cert_source
+ source:
+ id: get_mtls_endpoint_and_cert_source
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 262
+ summary: 'Return the API endpoint and client cert source for mutual TLS.
+
+
+ The client cert source is determined in the following order:
+
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true",
+ the
+
+ client cert source is None.
+
+ (2) if `client_options.client_cert_source` is provided, use the provided one;
+ if the
+
+ default client cert source exists, use the default one; otherwise the client cert
+
+ source is None.
+
+
+ The API endpoint is determined in the following order:
+
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use
+ the
+
+ default mTLS endpoint; if the environment variabel is "never", use the default
+ API
+
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint,
+ otherwise
+
+ use the default API endpoint.
+
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ '
+ syntax:
+ content: "get_mtls_endpoint_and_cert_source(\n client_options: typing.Optional[\n\
+ \ google.api_core.client_options.ClientOptions\n ] = None,\n)"
+ exceptions:
+ - description: If any errors happen.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - defaultValue: None
+ description: Custom options for the client. Only the api_endpoint
+ and client_cert_source properties may be used in this method.
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ returns:
+ - description: returns the API endpoint and the client cert source to use.
+ var_type: Tuple[str, Callable[[], Tuple[bytes, bytes]]]
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.list_voices
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: list_voices
+ source:
+ id: list_voices
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 428
+ summary: "Returns a list of Voice supported for synthesis.\n\n```python\n# This\
+ \ snippet has been automatically generated and should be regarded as a\n# code\
+ \ template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1beta1\n\ndef sample_list_voices():\n \
+ \ # Create a client\n client = texttospeech_v1beta1.TextToSpeechClient()\n\
+ \n # Initialize request argument(s)\n request = texttospeech_v1beta1.ListVoicesRequest(\n\
+ \ )\n\n # Make the request\n response = client.list_voices(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "list_voices(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.ListVoicesRequest,\
+ \ dict\n ]\n ] = None,\n *,\n language_code: typing.Optional[str]\
+ \ = None,\n retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.ListVoicesResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the ListVoices method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1beta1.types.ListVoicesRequest ,
+ dict]
+ - description: Optional. Recommended. BCP-47 __
+ language tag. If not specified, the API will return all supported voices.
+ If specified, the ListVoices call will only return voices that can be used
+ to synthesize this language_code. For example, if you specify "en-NZ",
+ all "en-NZ" voices will be returned. If you specify "no",
+ both "no-\*" (Norwegian) and "nb-\*" (Norwegian
+ Bokmal) voices will be returned. This corresponds to the language_code
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: language_code
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the ListVoices method.
+ var_type: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.list_voices
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: model_path
+ source:
+ id: model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 163
+ summary: 'Returns a fully-qualified model string.
+
+
+ '
+ syntax:
+ content: 'model_path(project: str, location: str, model: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_billing_account_path
+ source:
+ id: parse_common_billing_account_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 194
+ summary: 'Parse a billing_account path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_billing_account_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_folder_path
+ source:
+ id: parse_common_folder_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 209
+ summary: 'Parse a folder path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_folder_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_location_path
+ source:
+ id: parse_common_location_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 256
+ summary: 'Parse a location path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_location_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_organization_path
+ source:
+ id: parse_common_organization_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 224
+ summary: 'Parse a organization path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_organization_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_common_project_path
+ source:
+ id: parse_common_project_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 239
+ summary: 'Parse a project path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_project_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_model_path
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: parse_model_path
+ source:
+ id: parse_model_path
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 176
+ summary: 'Parses a model path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_model_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_model_path
+- attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: synthesize_speech
+ source:
+ id: synthesize_speech
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/client.py
+ startLine: 530
+ summary: "Synthesizes speech synchronously: receive results\nafter all text input\
+ \ has been processed.\n\n```python\n# This snippet has been automatically generated\
+ \ and should be regarded as a\n# code template only.\n# It will require modifications\
+ \ to work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google.cloud import texttospeech_v1beta1\n\ndef sample_synthesize_speech():\n\
+ \ # Create a client\n client = texttospeech_v1beta1.TextToSpeechClient()\n\
+ \n # Initialize request argument(s)\n input = texttospeech_v1beta1.SynthesisInput()\n\
+ \ input.text = \"text_value\"\n\n voice = texttospeech_v1beta1.VoiceSelectionParams()\n\
+ \ voice.language_code = \"language_code_value\"\n\n audio_config = texttospeech_v1beta1.AudioConfig()\n\
+ \ audio_config.audio_encoding = \"ALAW\"\n\n request = texttospeech_v1beta1.SynthesizeSpeechRequest(\n\
+ \ input=input,\n voice=voice,\n audio_config=audio_config,\n\
+ \ )\n\n # Make the request\n response = client.synthesize_speech(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "synthesize_speech(\n request: typing.Optional[\n typing.Union[\n\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.SynthesizeSpeechRequest,\n\
+ \ dict,\n ]\n ] = None,\n *,\n input: typing.Optional[\n\
+ \ google.cloud.texttospeech_v1beta1.types.cloud_tts.SynthesisInput\n\
+ \ ] = None,\n voice: typing.Optional[\n google.cloud.texttospeech_v1beta1.types.cloud_tts.VoiceSelectionParams\n\
+ \ ] = None,\n audio_config: typing.Optional[\n google.cloud.texttospeech_v1beta1.types.cloud_tts.AudioConfig\n\
+ \ ] = None,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.cloud.texttospeech_v1beta1.types.cloud_tts.SynthesizeSpeechResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. The top-level message sent by the client for
+ the SynthesizeSpeech method.
+ id: request
+ var_type: Union[google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest ,
+ dict]
+ - description: Required. The Synthesizer requires either plain text or SSML as
+ input. This corresponds to the input field on the request
+ instance; if request is provided, this should not be set.
+ id: input
+ var_type: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+ - description: Required. The desired voice of the synthesized audio. This corresponds
+ to the voice field on the request instance; if request
+ is provided, this should not be set.
+ id: voice
+ var_type: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+ - description: Required. The configuration of the synthesized audio. This corresponds
+ to the audio_config field on the request instance;
+ if request is provided, this should not be set.
+ id: audio_config
+ var_type: google.cloud.texttospeech_v1beta1.types.AudioConfig
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: The message returned to the client by the SynthesizeSpeech method.
+ var_type: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+ type: method
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+- &id001
+ attributes: []
+ class: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.transport
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: transport
+ source:
+ id: transport
+ path: null
+ startLine: null
+ summary: 'Returns the transport used by the client instance.
+
+ '
+ syntax:
+ returns:
+ - description: The transport used by the client instance.
+ var_type: TextToSpeechTransport
+ type: property
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.transport
+- *id001
+references:
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ isExternal: false
+ name: TextToSpeechClient
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.__exit__
+ isExternal: false
+ name: __exit__
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.__exit__
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+ isExternal: false
+ name: common_billing_account_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_billing_account_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_folder_path
+ isExternal: false
+ name: common_folder_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_folder_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_location_path
+ isExternal: false
+ name: common_location_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_location_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_organization_path
+ isExternal: false
+ name: common_organization_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_organization_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_project_path
+ isExternal: false
+ name: common_project_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.common_project_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+ isExternal: false
+ name: from_service_account_file
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_file
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+ isExternal: false
+ name: from_service_account_info
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_info
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+ isExternal: false
+ name: from_service_account_json
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.from_service_account_json
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+ isExternal: false
+ name: get_mtls_endpoint_and_cert_source
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.get_mtls_endpoint_and_cert_source
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.list_voices
+ isExternal: false
+ name: list_voices
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.list_voices
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.model_path
+ isExternal: false
+ name: model_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.model_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+ isExternal: false
+ name: parse_common_billing_account_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_billing_account_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+ isExternal: false
+ name: parse_common_folder_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_folder_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+ isExternal: false
+ name: parse_common_location_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_location_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+ isExternal: false
+ name: parse_common_organization_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_organization_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+ isExternal: false
+ name: parse_common_project_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_common_project_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_model_path
+ isExternal: false
+ name: parse_model_path
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.parse_model_path
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+ isExternal: false
+ name: synthesize_speech
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.synthesize_speech
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.transport
+ isExternal: false
+ name: transport
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient.transport
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.yml
new file mode 100644
index 000000000000..cec2caa30c81
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.services.text_to_speech.yml
@@ -0,0 +1,30 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ - google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ name: text_to_speech
+ source:
+ id: text_to_speech
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/services/text_to_speech/__init__.py
+ startLine: 0
+ summary: API documentation for `texttospeech_v1beta1.services.text_to_speech` package.
+ syntax: {}
+ type: subPackage
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech
+references:
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ isExternal: false
+ name: TextToSpeechAsyncClient
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+- fullName: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ isExternal: false
+ name: TextToSpeechClient
+ parent: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.AudioConfig.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.AudioConfig.yml
new file mode 100644
index 000000000000..f87ff5edd8ff
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.AudioConfig.yml
@@ -0,0 +1,65 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The format of the audio byte\n stream."
+ id: audio_encoding
+ var_type: google.cloud.texttospeech_v1beta1.types.AudioEncoding
+ - description: "Optional. Input only. Speaking rate/speed, in the range\n [0.25,\
+ \ 4.0]. 1.0 is the normal native speed supported by the\n specific voice.\
+ \ 2.0 is twice as fast, and 0.5 is half as\n fast. If unset(0.0), defaults\
+ \ to the native 1.0 speed. Any\n other values < 0.25 or > 4.0 will return\
+ \ an error."
+ id: speaking_rate
+ var_type: float
+ - description: "Optional. Input only. Speaking pitch, in the range [-20.0,\n 20.0].\
+ \ 20 means increase 20 semitones from the original\n pitch. -20 means decrease\
+ \ 20 semitones from the original\n pitch."
+ id: pitch
+ var_type: float
+ - description: "Optional. Input only. Volume gain (in dB) of the normal\n native\
+ \ volume supported by the specific voice, in the range\n [-96.0, 16.0]. If\
+ \ unset, or set to a value of 0.0 (dB), will\n play at normal native signal\
+ \ amplitude. A value of -6.0 (dB)\n will play at approximately half the amplitude\
+ \ of the normal\n native signal amplitude. A value of +6.0 (dB) will play\
+ \ at\n approximately twice the amplitude of the normal native\n signal amplitude.\
+ \ Strongly recommend not to exceed +10 (dB)\n as there's usually no effective\
+ \ increase in loudness for any\n value greater than that."
+ id: volume_gain_db
+ var_type: float
+ - description: "Optional. The synthesis sample rate (in hertz) for this\n audio.\
+ \ When this is specified in SynthesizeSpeechRequest, if\n this is different\
+ \ from the voice's natural sample rate, then\n the synthesizer will honor\
+ \ this request by converting to the\n desired sample rate (which might result\
+ \ in worse audio\n quality), unless the specified sample rate is not supported\n\
+ \ for the encoding chosen, in which case it will fail the\n request and\
+ \ return [google.rpc.Code.INVALID_ARGUMENT][]."
+ id: sample_rate_hertz
+ var_type: int
+ - description: "Optional. Input only. An identifier which selects 'audio\n effects'\
+ \ profiles that are applied on (post synthesized)\n text to speech. Effects\
+ \ are applied on top of each other in\n the order they are given. See `audio\n\
+ \ profiles `__\n\
+ \ for current supported profile ids."
+ id: effects_profile_id
+ var_type: Sequence[str]
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.AudioConfig
+ fullName: google.cloud.texttospeech_v1beta1.types.AudioConfig
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: AudioConfig
+ source:
+ id: AudioConfig
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 279
+ summary: 'Description of audio data to be synthesized.
+
+ '
+ syntax:
+ content: AudioConfig(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.AudioConfig
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.AudioEncoding.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.AudioEncoding.yml
new file mode 100644
index 000000000000..1bc831bdb10e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.AudioEncoding.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.AudioEncoding
+ fullName: google.cloud.texttospeech_v1beta1.types.AudioEncoding
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: AudioEncoding
+ source:
+ id: AudioEncoding
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 47
+ summary: 'Configuration to set up audio encoder. The encoding
+
+ determines the output audio format that we''d like.
+
+
+ '
+ syntax:
+ content: AudioEncoding(value)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.AudioEncoding
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage.yml
new file mode 100644
index 000000000000..cca7511ff6dc
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage.yml
@@ -0,0 +1,29 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
+ fullName: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ name: ReportedUsage
+ source:
+ id: ReportedUsage
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 365
+ summary: 'The usage of the synthesized audio. You must report your
+
+ honest and correct usage of the service as it''s regulated by
+
+ contract and will cause significant difference in billing.
+
+
+ '
+ syntax:
+ content: ReportedUsage(value)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.yml
new file mode 100644
index 000000000000..5fc9b169259e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.yml
@@ -0,0 +1,37 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the AutoML model that\n synthesizes the\
+ \ custom voice."
+ id: model
+ var_type: str
+ - description: "Optional. The usage of the synthesized audio\n to be reported."
+ id: reported_usage
+ var_type: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
+ children:
+ - google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
+ class: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ fullName: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: CustomVoiceParams
+ source:
+ id: CustomVoiceParams
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 353
+ summary: 'Description of the custom voice to be synthesized.
+
+ '
+ syntax:
+ content: CustomVoiceParams(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+references:
+- fullName: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
+ isExternal: false
+ name: ReportedUsage
+ parent: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ uid: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.ListVoicesRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.ListVoicesRequest.yml
new file mode 100644
index 000000000000..3af9ee357a06
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.ListVoicesRequest.yml
@@ -0,0 +1,35 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Optional. Recommended.\n BCP-47 __\n\
+ \ language tag. If not specified, the API will return all\n supported voices.\
+ \ If specified, the ListVoices call will\n only return voices that can be\
+ \ used to synthesize this\n language_code. For example, if you specify \"\
+ en-NZ\", all\n \"en-NZ\" voices will be returned. If you\
+ \ specify\n \"no\", both \"no-\\*\" (Norwegian)\
+ \ and \"nb-\\*\"\n (Norwegian Bokmal) voices will be returned."
+ id: language_code
+ var_type: str
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.ListVoicesRequest
+ fullName: google.cloud.texttospeech_v1beta1.types.ListVoicesRequest
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: ListVoicesRequest
+ source:
+ id: ListVoicesRequest
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 60
+ summary: 'The top-level message sent by the client for the `ListVoices`
+
+ method.
+
+ '
+ syntax:
+ content: ListVoicesRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.ListVoicesRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.ListVoicesResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.ListVoicesResponse.yml
new file mode 100644
index 000000000000..a36fd7547685
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.ListVoicesResponse.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: The list of voices.
+ id: voices
+ var_type: Sequence[google.cloud.texttospeech_v1beta1.types.Voice ]
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+ fullName: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: ListVoicesResponse
+ source:
+ id: ListVoicesResponse
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 83
+ summary: 'The message returned to the client by the `ListVoices` method.
+
+ '
+ syntax:
+ content: ListVoicesResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender.yml
new file mode 100644
index 000000000000..e1d570ea9311
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+ fullName: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: SsmlVoiceGender
+ source:
+ id: SsmlVoiceGender
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 37
+ summary: 'Gender of the voice as described in `SSML voice
+
+ element `__.
+
+
+ '
+ syntax:
+ content: SsmlVoiceGender(value)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesisInput.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesisInput.yml
new file mode 100644
index 000000000000..992950e02ed3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesisInput.yml
@@ -0,0 +1,52 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The raw text to be synthesized.\n \n This field is a member\
+ \ of oneof_ input_source."
+ id: text
+ var_type: str
+ - description: "The SSML document to be synthesized. The SSML document must\n \
+ \ be valid and well-formed. Otherwise the RPC will fail and\n return [google.rpc.Code.INVALID_ARGUMENT][].\
+ \ For more\n information, see\n SSML __.\n\
+ \ \n This field is a member of oneof_ input_source."
+ id: ssml
+ var_type: str
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+ fullName: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: SynthesisInput
+ source:
+ id: SynthesisInput
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 183
+ summary: 'Contains text input to be synthesized. Either `text` or `ssml`
+
+ must be supplied. Supplying both or neither returns
+
+ [google.rpc.Code.INVALID_ARGUMENT][]. The input size is limited to
+
+ 5000 characters.
+
+
+ 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
+
+ '
+ syntax:
+ content: SynthesisInput(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType.yml
new file mode 100644
index 000000000000..628b31be67b8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType
+ fullName: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ name: TimepointType
+ source:
+ id: TimepointType
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 154
+ summary: 'The type of timepoint information that is returned in the
+
+ response.
+
+
+ '
+ syntax:
+ content: TimepointType(value)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.yml
new file mode 100644
index 000000000000..8b61f35784ee
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.yml
@@ -0,0 +1,46 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The Synthesizer requires either\n plain text or SSML\
+ \ as input."
+ id: input
+ var_type: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+ - description: "Required. The desired voice of the\n synthesized audio."
+ id: voice
+ var_type: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+ - description: "Required. The configuration of the\n synthesized audio."
+ id: audio_config
+ var_type: google.cloud.texttospeech_v1beta1.types.AudioConfig
+ - description: "Whether and what timepoints are returned in\n the response."
+ id: enable_time_pointing
+ var_type: Sequence[google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType ]
+ children:
+ - google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType
+ class: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ fullName: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: SynthesizeSpeechRequest
+ source:
+ id: SynthesizeSpeechRequest
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 135
+ summary: 'The top-level message sent by the client for the
+
+ `SynthesizeSpeech` method.
+
+ '
+ syntax:
+ content: SynthesizeSpeechRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+references:
+- fullName: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType
+ isExternal: false
+ name: TimepointType
+ parent: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse.yml
new file mode 100644
index 000000000000..eba856dd9752
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse.yml
@@ -0,0 +1,42 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The audio data bytes encoded as specified in the request,\n including\
+ \ the header for encodings that are wrapped in\n containers (e.g. MP3, OGG_OPUS).\
+ \ For LINEAR16 audio, we\n include the WAV header. Note: as with all bytes\
+ \ fields,\n protobuffers use a pure binary representation, whereas JSON\n\
+ \ representations use base64."
+ id: audio_content
+ var_type: bytes
+ - description: "A link between a position in the original request input and\n \
+ \ a corresponding time in the output audio. It's only\n supported via google.cloud.texttospeech_v1beta1.types.Timepoint ]
+ - description: The audio metadata of audio_content.
+ id: audio_config
+ var_type: google.cloud.texttospeech_v1beta1.types.AudioConfig
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+ fullName: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: SynthesizeSpeechResponse
+ source:
+ id: SynthesizeSpeechResponse
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 385
+ summary: 'The message returned to the client by the `SynthesizeSpeech`
+
+ method.
+
+ '
+ syntax:
+ content: SynthesizeSpeechResponse(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.Timepoint.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.Timepoint.yml
new file mode 100644
index 000000000000..4f1b6ee7a709
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.Timepoint.yml
@@ -0,0 +1,33 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Timepoint name as received from the client within BCP-47\
+ \ __\n language tags\
+ \ (e.g. \"en-US\", \"es-419\", \"cmn-tw\")."
+ id: language_codes
+ var_type: Sequence[str]
+ - description: "The name of this voice. Each distinct voice\n has a unique name."
+ id: name
+ var_type: str
+ - description: The gender of this voice.
+ id: ssml_gender
+ var_type: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+ - description: "The natural sample rate (in hertz) for this\n voice."
+ id: natural_sample_rate_hertz
+ var_type: int
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.Voice
+ fullName: google.cloud.texttospeech_v1beta1.types.Voice
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: Voice
+ source:
+ id: Voice
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 98
+ summary: 'Description of a voice supported by the TTS service.
+
+ '
+ syntax:
+ content: Voice(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.Voice
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams.yml
new file mode 100644
index 000000000000..f97a9b9a098f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams.yml
@@ -0,0 +1,53 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The language (and potentially also the region) of\n \
+ \ the voice expressed as a\n BCP-47 __\n\
+ \ language tag, e.g. \"en-US\". This should not include a script\n tag (e.g.\
+ \ use \"cmn-cn\" rather than \"cmn-Hant-cn\"), because\n the script will be\
+ \ inferred from the input provided in the\n SynthesisInput. The TTS service\
+ \ will use this parameter to\n help choose an appropriate voice. Note that\
+ \ the TTS service\n may choose a voice with a slightly different language\
+ \ code\n than the one selected; it may substitute a different region\n (e.g.\
+ \ using en-US rather than en-CA if there isn't a\n Canadian voice available),\
+ \ or even a different language,\n e.g. using \"nb\" (Norwegian Bokmal) instead\
+ \ of \"no\"\n (Norwegian)\"."
+ id: language_code
+ var_type: str
+ - description: "The name of the voice. If not set, the service will choose a\n \
+ \ voice based on the other parameters such as language_code\n and gender."
+ id: name
+ var_type: str
+ - description: "The preferred gender of the voice. If not set, the service\n will\
+ \ choose a voice based on the other parameters such as\n language_code and\
+ \ name. Note that this is only a preference,\n not requirement; if a voice\
+ \ of the appropriate gender is not\n available, the synthesizer should substitute\
+ \ a voice with a\n different gender rather than failing the request."
+ id: ssml_gender
+ var_type: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+ - description: "The configuration for a custom voice. If\n [CustomVoiceParams.model]\
+ \ is set, the service will choose\n the custom voice matching the specified\
+ \ configuration."
+ id: custom_voice
+ var_type: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ children: []
+ class: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+ fullName: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: VoiceSelectionParams
+ source:
+ id: VoiceSelectionParams
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/cloud_tts.py
+ startLine: 223
+ summary: 'Description of which voice to use for a synthesis request.
+
+ '
+ syntax:
+ content: VoiceSelectionParams(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.yml
new file mode 100644
index 000000000000..cf050947f434
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/google.cloud.texttospeech_v1beta1.types.yml
@@ -0,0 +1,90 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.texttospeech_v1beta1.types.AudioConfig
+ - google.cloud.texttospeech_v1beta1.types.AudioEncoding
+ - google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ - google.cloud.texttospeech_v1beta1.types.ListVoicesRequest
+ - google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+ - google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+ - google.cloud.texttospeech_v1beta1.types.SynthesisInput
+ - google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ - google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+ - google.cloud.texttospeech_v1beta1.types.Timepoint
+ - google.cloud.texttospeech_v1beta1.types.Voice
+ - google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+ fullName: google.cloud.texttospeech_v1beta1.types
+ langs:
+ - python
+ module: google.cloud.texttospeech_v1beta1.types
+ name: types
+ source:
+ id: types
+ path: tests/testdata/gapic-auto/google/cloud/texttospeech_v1beta1/types/__init__.py
+ startLine: 0
+ summary: API documentation for `texttospeech_v1beta1.types` package.
+ syntax: {}
+ type: subPackage
+ uid: google.cloud.texttospeech_v1beta1.types
+references:
+- fullName: google.cloud.texttospeech_v1beta1.types.AudioConfig
+ isExternal: false
+ name: AudioConfig
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.AudioConfig
+- fullName: google.cloud.texttospeech_v1beta1.types.AudioEncoding
+ isExternal: false
+ name: AudioEncoding
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.AudioEncoding
+- fullName: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ isExternal: false
+ name: CustomVoiceParams
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+- fullName: google.cloud.texttospeech_v1beta1.types.ListVoicesRequest
+ isExternal: false
+ name: ListVoicesRequest
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.ListVoicesRequest
+- fullName: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+ isExternal: false
+ name: ListVoicesResponse
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+- fullName: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+ isExternal: false
+ name: SsmlVoiceGender
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+- fullName: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+ isExternal: false
+ name: SynthesisInput
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+- fullName: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ isExternal: false
+ name: SynthesizeSpeechRequest
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+- fullName: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+ isExternal: false
+ name: SynthesizeSpeechResponse
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+- fullName: google.cloud.texttospeech_v1beta1.types.Timepoint
+ isExternal: false
+ name: Timepoint
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.Timepoint
+- fullName: google.cloud.texttospeech_v1beta1.types.Voice
+ isExternal: false
+ name: Voice
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.Voice
+- fullName: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+ isExternal: false
+ name: VoiceSelectionParams
+ parent: google.cloud.texttospeech_v1beta1.types
+ uid: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/index.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/index.md
new file mode 100644
index 000000000000..4c377712327a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/index.md
@@ -0,0 +1,87 @@
+# Python Client for Google Cloud Text-to-Speech API
+
+[](https://github.com/googleapis/google-cloud-python/blob/main/README.rst#stability-levels) [](https://pypi.org/project/google-cloud-texttospeech/) [](https://pypi.org/project/google-cloud-texttospeech/)
+
+[Google Cloud Text-to-Speech API](https://cloud.google.com/text-to-speech): enables easy integration of Google text recognition technologies into developer applications. Send text and receive synthesized audio output from the Cloud Text-to-Speech API service.
+
+
+* [Client Library Documentation](https://cloud.google.com/python/docs/reference/texttospeech/latest)
+
+
+* [Product Documentation](https://cloud.google.com/text-to-speech)
+
+## Quick Start
+
+In order to use this library, you first need to go through the following steps:
+
+
+1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+
+
+2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+
+
+3. [Enable the Google Cloud Text-to-Speech API.](https://cloud.google.com/text-to-speech)
+
+
+4. [Setup Authentication.](https://googleapis.dev/python/google-api-core/latest/auth.html)
+
+### Installation
+
+Install this library in a [virtualenv](https://virtualenv.pypa.io/en/latest/) using pip. [virtualenv](https://virtualenv.pypa.io/en/latest/) is a tool to
+create isolated Python environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
+
+With [virtualenv](https://virtualenv.pypa.io/en/latest/), it’s possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
+
+### Code samples and snippets
+
+Code samples and snippets live in the samples/ folder.
+
+#### Supported Python Versions
+
+Our client libraries are compatible with all current [active](https://devguide.python.org/devcycle/#in-development-main-branch) and [maintenance](https://devguide.python.org/devcycle/#maintenance-branches) versions of
+Python.
+
+Python >= 3.7
+
+#### Unsupported Python Versions
+
+Python <= 3.6
+
+If you are using an [end-of-life](https://devguide.python.org/devcycle/#end-of-life-branches)
+version of Python, we recommend that you update as soon as possible to an actively supported version.
+
+#### Mac/Linux
+
+```console
+pip install virtualenv
+virtualenv
+source /bin/activate
+/bin/pip install google-cloud-texttospeech
+```
+
+#### Windows
+
+```console
+pip install virtualenv
+virtualenv
+\Scripts\activate
+\Scripts\pip.exe install google-cloud-texttospeech
+```
+
+### Next Steps
+
+
+* Read the [Client Library Documentation](https://cloud.google.com/python/docs/reference/texttospeech/latest) for Google Cloud Text-to-Speech API
+to see other available methods on the client.
+
+
+* Read the [Google Cloud Text-to-Speech API Product documentation](https://cloud.google.com/text-to-speech) to learn
+more about the product and see How-to Guides.
+
+
+* View this [README](https://github.com/googleapis/google-cloud-python/blob/main/README.rst) to see the full list of Cloud
+APIs that we cover.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/multiprocessing.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/multiprocessing.md
new file mode 100644
index 000000000000..ac442c0c7185
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/multiprocessing.md
@@ -0,0 +1,7 @@
+# Multiprocessing
+
+**NOTE**: Because this client uses [`grpc`](https://grpc.github.io/grpc/python/grpc.html#module-grpc) library, it is safe to
+share instances across threads. In multiprocessing scenarios, the best
+practice is to create client instances *after* the invocation of
+[`os.fork()`](https://python.readthedocs.io/en/latest/library/os.html#os.fork) by [`multiprocessing.pool.Pool`](https://python.readthedocs.io/en/latest/library/multiprocessing.html#multiprocessing.pool.Pool) or
+[`multiprocessing.Process`](https://python.readthedocs.io/en/latest/library/multiprocessing.html#multiprocessing.Process).
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/toc.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/toc.yml
new file mode 100644
index 000000000000..8460a986dadb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/toc.yml
@@ -0,0 +1,103 @@
+- items:
+ - href: index.md
+ name: Overview
+ - href: changelog.md
+ name: Changelog
+ - href: multiprocessing.md
+ name: Multiprocessing
+ - href: upgrading.md
+ name: 2.0.0 Migration Guide
+ - items:
+ - items:
+ - name: Overview
+ uid: google.cloud.texttospeech_v1.services.text_to_speech
+ - name: TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechAsyncClient
+ - name: TextToSpeechClient
+ uid: google.cloud.texttospeech_v1.services.text_to_speech.TextToSpeechClient
+ name: text_to_speech
+ uid: google.cloud.texttospeech_v1.services.text_to_speech
+ - items:
+ - name: Overview
+ uid: google.cloud.texttospeech_v1.types
+ - name: AudioConfig
+ uid: google.cloud.texttospeech_v1.types.AudioConfig
+ - name: AudioEncoding
+ uid: google.cloud.texttospeech_v1.types.AudioEncoding
+ - items:
+ - name: Overview
+ uid: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ - name: ReportedUsage
+ uid: google.cloud.texttospeech_v1.types.CustomVoiceParams.ReportedUsage
+ name: CustomVoiceParams
+ uid: google.cloud.texttospeech_v1.types.CustomVoiceParams
+ - name: ListVoicesRequest
+ uid: google.cloud.texttospeech_v1.types.ListVoicesRequest
+ - name: ListVoicesResponse
+ uid: google.cloud.texttospeech_v1.types.ListVoicesResponse
+ - name: SsmlVoiceGender
+ uid: google.cloud.texttospeech_v1.types.SsmlVoiceGender
+ - name: SynthesisInput
+ uid: google.cloud.texttospeech_v1.types.SynthesisInput
+ - name: SynthesizeSpeechRequest
+ uid: google.cloud.texttospeech_v1.types.SynthesizeSpeechRequest
+ - name: SynthesizeSpeechResponse
+ uid: google.cloud.texttospeech_v1.types.SynthesizeSpeechResponse
+ - name: Voice
+ uid: google.cloud.texttospeech_v1.types.Voice
+ - name: VoiceSelectionParams
+ uid: google.cloud.texttospeech_v1.types.VoiceSelectionParams
+ name: types
+ uid: google.cloud.texttospeech_v1.types
+ name: Texttospeech V1
+ - items:
+ - items:
+ - name: Overview
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ - name: TextToSpeechAsyncClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechAsyncClient
+ - name: TextToSpeechClient
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech.TextToSpeechClient
+ name: text_to_speech
+ uid: google.cloud.texttospeech_v1beta1.services.text_to_speech
+ - items:
+ - name: Overview
+ uid: google.cloud.texttospeech_v1beta1.types
+ - name: AudioConfig
+ uid: google.cloud.texttospeech_v1beta1.types.AudioConfig
+ - name: AudioEncoding
+ uid: google.cloud.texttospeech_v1beta1.types.AudioEncoding
+ - items:
+ - name: Overview
+ uid: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ - name: ReportedUsage
+ uid: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams.ReportedUsage
+ name: CustomVoiceParams
+ uid: google.cloud.texttospeech_v1beta1.types.CustomVoiceParams
+ - name: ListVoicesRequest
+ uid: google.cloud.texttospeech_v1beta1.types.ListVoicesRequest
+ - name: ListVoicesResponse
+ uid: google.cloud.texttospeech_v1beta1.types.ListVoicesResponse
+ - name: SsmlVoiceGender
+ uid: google.cloud.texttospeech_v1beta1.types.SsmlVoiceGender
+ - name: SynthesisInput
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesisInput
+ - items:
+ - name: Overview
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ - name: TimepointType
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest.TimepointType
+ name: SynthesizeSpeechRequest
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechRequest
+ - name: SynthesizeSpeechResponse
+ uid: google.cloud.texttospeech_v1beta1.types.SynthesizeSpeechResponse
+ - name: Timepoint
+ uid: google.cloud.texttospeech_v1beta1.types.Timepoint
+ - name: Voice
+ uid: google.cloud.texttospeech_v1beta1.types.Voice
+ - name: VoiceSelectionParams
+ uid: google.cloud.texttospeech_v1beta1.types.VoiceSelectionParams
+ name: types
+ uid: google.cloud.texttospeech_v1beta1.types
+ name: Texttospeech V1beta1
+ name: google-cloud-texttospeech
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/upgrading.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/upgrading.md
new file mode 100644
index 000000000000..505577990d5c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-auto/upgrading.md
@@ -0,0 +1,151 @@
+# 2.0.0 Migration Guide
+
+The 2.0 release of the `google-cloud-texttospeech` client is a significant upgrade based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python), and includes substantial interface changes. Existing code written for earlier versions of this library will likely require updates to use this version. This document describes the changes that have been made, and what you need to do to update your usage.
+
+If you experience issues or have questions, please file an [issue](https://github.com/googleapis/python-texttospeech/issues).
+
+## Supported Python Versions
+
+> **WARNING**: Breaking change
+
+The 2.0.0 release requires Python 3.6+.
+
+## Method Calls
+
+> **WARNING**: Breaking change
+
+Methods expect request objects. We provide a script that will convert most common use cases.
+
+
+* Install the library and `libcst`.
+
+```py
+python3 -m pip install google-cloud-texttospeech libcst
+```
+
+
+* The script `fixup_keywords.py` is shipped with the library. It expects
+an input directory (with the code to convert) and an empty destination directory.
+
+```sh
+$ fixup_keywords.py --input-directory .samples/ --output-directory samples/
+```
+
+**Before:**
+
+```py
+from google.cloud import texttospeech
+
+client = texttospeech.TextToSpeechClient()
+
+voices = client.list_voices(language_code="no")
+```
+
+**After:**
+
+```py
+from google.cloud import texttospeech
+
+client = texttospeech.TextToSpeechClient()
+
+voices = client.list_voices(request={"language_code": "no"})
+```
+
+### More Details
+
+In `google-cloud-texttospeech<2.0.0`, parameters required by the API were positional parameters and optional parameters were keyword parameters.
+
+**Before:**
+
+```py
+ def synthesize_speech(
+ self,
+ input_,
+ voice,
+ audio_config,
+ retry=google.api_core.gapic_v1.method.DEFAULT,
+ timeout=google.api_core.gapic_v1.method.DEFAULT,
+ metadata=None,
+ ):
+```
+
+In the 2.0.0 release, all methods have a single positional parameter `request`. Method docstrings indicate whether a parameter is required or optional.
+
+Some methods have additional keyword only parameters. The available parameters depend on the [`google.api.method_signature` annotation](https://github.com/googleapis/googleapis/blob/master/google/cloud/texttospeech/v1/cloud_tts.proto#L53) specified by the API producer.
+
+**After:**
+
+```py
+ def synthesize_speech(
+ self,
+ request: cloud_tts.SynthesizeSpeechRequest = None,
+ *,
+ input: cloud_tts.SynthesisInput = None,
+ voice: cloud_tts.VoiceSelectionParams = None,
+ audio_config: cloud_tts.AudioConfig = None,
+ retry: retries.Retry = gapic_v1.method.DEFAULT,
+ timeout: float = None,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> cloud_tts.SynthesizeSpeechResponse:
+```
+
+> **NOTE:** The `request` parameter and flattened keyword parameters for the API are mutually exclusive.
+> Passing both will result in an error.
+
+Both of these calls are valid:
+
+```py
+response = client.synthesize_speech(
+ request={
+ "input": input_text,
+ "voice": voice,
+ "audio_config": audio_config
+ }
+)
+```
+
+```py
+response = client.synthesize_speech(
+ input=input_text,
+ voice=voice,
+ audio_config=audio_config
+)
+```
+
+This call is invalid because it mixes `request` with a keyword argument `audio_config`. Executing this code
+will result in an error.
+
+```py
+response = client.synthesize_speech(
+ request={
+ "input": input_text,
+ "voice": voice,
+ },
+ audio_config=audio_config
+)
+```
+
+## Enums and Types
+
+> **WARNING**: Breaking change
+
+The submodules `enums` and `types` have been removed.
+
+**Before:**
+
+```py
+
+from google.cloud import texttospeech
+
+encoding = texttospeech.enums.AudioEncoding.MP3
+voice = texttospeech.types.VoiceSelectionParams(language_code="en-US")
+```
+
+**After:**
+
+```py
+from google.cloud import texttospeech
+
+encoding = texttospeech.AudioEncoding.MP3
+voice = texttospeech.VoiceSelectionParams(language_code="en-US")
+```
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/changelog.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/changelog.md
new file mode 100644
index 000000000000..d0bb2e310d16
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/changelog.md
@@ -0,0 +1,1685 @@
+# Changelog
+
+[PyPI History](https://pypi.org/project/google-cloud-pubsub/#history)
+
+## [2.13.10](https://github.com/googleapis/python-pubsub/compare/v2.13.8...v2.13.10) (2022-10-14)
+
+### Bug Fixes
+
+
+* Batch at most 1,000 ack ids per request ([#802](https://github.com/googleapis/python-pubsub/issues/802)) ([4361e67](https://github.com/googleapis/python-pubsub/commit/4361e6735004a5600ee73979b99e6b9dd587c49b))
+
+
+* **deps:** Allow protobuf 3.19.5 ([#801](https://github.com/googleapis/python-pubsub/issues/801)) ([fa23503](https://github.com/googleapis/python-pubsub/commit/fa235033481783c2ec378b2a26b223bdff206461))
+
+
+* Silence invalid_ack_id warnings for receipt modacks ([#798](https://github.com/googleapis/python-pubsub/issues/798)) ([17feea5](https://github.com/googleapis/python-pubsub/commit/17feea5783f3a878b4dcfb3a8570585f7637378f))
+
+### Miscellaneous Chores
+
+
+* release as 2.13.10 ([34f022b](https://github.com/googleapis/python-pubsub/commit/34f022b4ee62d53a193bc2babafad508e2f2540b))
+
+## [2.13.8](https://github.com/googleapis/python-pubsub/compare/v2.13.7...v2.13.8) (2022-10-03)
+
+### Bug Fixes
+
+
+* **deps:** Require protobuf >= 3.20.2 ([#792](https://github.com/googleapis/python-pubsub/issues/792)) ([1a54f7c](https://github.com/googleapis/python-pubsub/commit/1a54f7cd3d997270e0a5d70f7caea32d8753be76))
+
+## [2.13.7](https://github.com/googleapis/python-pubsub/compare/v2.13.6...v2.13.7) (2022-09-22)
+
+### Bug Fixes
+
+
+* Remove expired ack_ids ([#787](https://github.com/googleapis/python-pubsub/issues/787)) ([b4b809d](https://github.com/googleapis/python-pubsub/commit/b4b809d616cf93881815d6baadf2dd322ab566d1))
+
+## [2.13.6](https://github.com/googleapis/python-pubsub/compare/v2.13.5...v2.13.6) (2022-08-11)
+
+### Bug Fixes
+
+
+* **deps:** allow protobuf < 5.0.0 ([#762](https://github.com/googleapis/python-pubsub/issues/762)) ([260bd18](https://github.com/googleapis/python-pubsub/commit/260bd183ffe19992be9a1c1d298438c1f44d3fa9))
+
+
+* **deps:** require proto-plus >= 1.22.0 ([260bd18](https://github.com/googleapis/python-pubsub/commit/260bd183ffe19992be9a1c1d298438c1f44d3fa9))
+
+
+* set stream_ack_deadline to max_duration_per_lease_extension or 60 s, set ack_deadline to min_duration_per_lease_extension or 10 s ([#760](https://github.com/googleapis/python-pubsub/issues/760)) ([4444129](https://github.com/googleapis/python-pubsub/commit/4444129b28a19296752e865b73827b78e99adea5))
+
+
+* Update stream_ack_deadline with ack_deadline ([#763](https://github.com/googleapis/python-pubsub/issues/763)) ([e600ad8](https://github.com/googleapis/python-pubsub/commit/e600ad8228930445765ffa0c45500a7779e25817))
+
+## [2.13.5](https://github.com/googleapis/python-pubsub/compare/v2.13.4...v2.13.5) (2022-08-10)
+
+### Documentation
+
+
+* reorganize sphinx structure ([#751](https://github.com/googleapis/python-pubsub/issues/751)) ([b6de574](https://github.com/googleapis/python-pubsub/commit/b6de57458a1976a068dd229208b9b678a9d3f866))
+
+## [2.13.4](https://github.com/googleapis/python-pubsub/compare/v2.13.3...v2.13.4) (2022-07-15)
+
+### Bug Fixes
+
+
+* Remove bidi modacks on StreamingPull initial request ([#738](https://github.com/googleapis/python-pubsub/issues/738)) ([1e7d469](https://github.com/googleapis/python-pubsub/commit/1e7d46901c4472a3534980621e88d81aa2e50760))
+
+## [2.13.3](https://github.com/googleapis/python-pubsub/compare/v2.13.2...v2.13.3) (2022-07-13)
+
+### Bug Fixes
+
+
+* **deps:** require google-api-core>=1.32.0,>=2.8.0 ([#735](https://github.com/googleapis/python-pubsub/issues/735)) ([a5624fb](https://github.com/googleapis/python-pubsub/commit/a5624fbee2951c7f0c3e413d7d399a41fa0aa4bf))
+
+## [2.13.2](https://github.com/googleapis/python-pubsub/compare/v2.13.1...v2.13.2) (2022-07-08)
+
+### Bug Fixes
+
+
+* **deps:** require google-api-core >= 2.8.0 ([#726](https://github.com/googleapis/python-pubsub/issues/726)) ([c80ad41](https://github.com/googleapis/python-pubsub/commit/c80ad41abf36c709f8299a6fa22f3672705b1b6d))
+
+## [2.13.1](https://github.com/googleapis/python-pubsub/compare/v2.13.0...v2.13.1) (2022-07-07)
+
+### Bug Fixes
+
+
+* change info logs to debug ([#693](https://github.com/googleapis/python-pubsub/issues/693)) ([950fbce](https://github.com/googleapis/python-pubsub/commit/950fbce009fd56a55feea971f8e6083fa84d54fc))
+
+
+* require python 3.7+ ([#730](https://github.com/googleapis/python-pubsub/issues/730)) ([0d949b8](https://github.com/googleapis/python-pubsub/commit/0d949b8da096d1b0a5e26f607b1cd79fb560252a))
+
+## [2.13.0](https://github.com/googleapis/python-pubsub/compare/v2.12.1...v2.13.0) (2022-06-06)
+
+### Features
+
+
+* add BigQuery configuration for subscriptions ([#685](https://github.com/googleapis/python-pubsub/issues/685)) ([6fa03be](https://github.com/googleapis/python-pubsub/commit/6fa03be779d6a7105bb7c029b95d4c357d2a49df))
+
+### Bug Fixes
+
+
+* add info log for bidi streaming pull ack_deadline requests ([#692](https://github.com/googleapis/python-pubsub/issues/692)) ([fcb67dd](https://github.com/googleapis/python-pubsub/commit/fcb67dd0d8fff5a583ebe0a3a08d0219601df8e9))
+
+
+* **deps:** require protobuf <4.0.0dev ([#699](https://github.com/googleapis/python-pubsub/issues/699)) ([dcdf013](https://github.com/googleapis/python-pubsub/commit/dcdf0137905949662ce191adcb6dd588bd74f9fe))
+
+### Documentation
+
+
+* fix changelog header to consistent size ([#700](https://github.com/googleapis/python-pubsub/issues/700)) ([93f2b62](https://github.com/googleapis/python-pubsub/commit/93f2b62a18f622d8da71043a6b6d3f53295db308))
+
+## [2.12.1](https://github.com/googleapis/python-pubsub/compare/v2.12.0...v2.12.1) (2022-05-11)
+
+### Bug Fixes
+
+
+* Add emulator support to schema service ([#658](https://github.com/googleapis/python-pubsub/issues/658)) ([1a07d7c](https://github.com/googleapis/python-pubsub/commit/1a07d7ce3b3580191f74b7895dd1b8afb13baccb))
+
+
+* Handle duplicate acks with streaming pull ([#662](https://github.com/googleapis/python-pubsub/issues/662)) ([219491e](https://github.com/googleapis/python-pubsub/commit/219491ea1e615f33e1955e3afc204a0281c525db))
+
+
+* set min snooze on lease management to .01 sec ([#678](https://github.com/googleapis/python-pubsub/issues/678)) ([91c6e69](https://github.com/googleapis/python-pubsub/commit/91c6e69e96953919bc86004692edd3a52c7b9796))
+
+### Documentation
+
+
+* fix project_path typo in UPGRADING.md ([#660](https://github.com/googleapis/python-pubsub/issues/660)) ([20d661c](https://github.com/googleapis/python-pubsub/commit/20d661c8562cc1f777ac7b3f1ba03dcad7a831c0))
+
+
+* mark eod as preview ([#657](https://github.com/googleapis/python-pubsub/issues/657)) ([418e1a3](https://github.com/googleapis/python-pubsub/commit/418e1a3783441469713ca8ec8776007ff0fdb15d))
+
+## [2.12.0](https://github.com/googleapis/python-pubsub/compare/v2.11.0...v2.12.0) (2022-04-06)
+
+### Features
+
+
+* increase GRPC max metadata size to 4 MB ([#623](https://github.com/googleapis/python-pubsub/issues/623)) ([54b9e07](https://github.com/googleapis/python-pubsub/commit/54b9e07401b7309f16ecfe2a7afc36ea69f24a9c))
+
+### Bug Fixes
+
+
+* mypy errors ([#622](https://github.com/googleapis/python-pubsub/issues/622)) ([dab13d5](https://github.com/googleapis/python-pubsub/commit/dab13d5fb1d723c971cd84ae20f18462e624a26d))
+
+
+* process ErrorInfo / GRPC errors for ack/modack only when exactly-once delivery is enabled ([#626](https://github.com/googleapis/python-pubsub/issues/626)) ([cc1953b](https://github.com/googleapis/python-pubsub/commit/cc1953bcf942fb394a92ba50ba615adf822bfe7d))
+
+## [2.11.0](https://github.com/googleapis/python-pubsub/compare/v2.10.0...v2.11.0) (2022-03-09)
+
+### Features
+
+
+* retry temporary GRPC statuses for ack/modack/nack when exactly-once delivery is enabled ([#607](https://github.com/googleapis/python-pubsub/issues/607)) ([a91bed8](https://github.com/googleapis/python-pubsub/commit/a91bed829c9040fcc6c1e70b99b66188ac4ded40))
+
+
+* return singleton success future for exactly-once methods in Message ([#608](https://github.com/googleapis/python-pubsub/issues/608)) ([253ced2](https://github.com/googleapis/python-pubsub/commit/253ced28f308450c7a1a93cc38f6d101ecd7d4c0))
+
+### Bug Fixes
+
+
+* **deps:** require google-api-core>=1.31.5, >=2.3.2 ([#600](https://github.com/googleapis/python-pubsub/issues/600)) ([1608b7f](https://github.com/googleapis/python-pubsub/commit/1608b7ffdd5b5db87e1e55fde763440ca9a4086e))
+
+
+* **deps:** require proto-plus>=1.15.0 ([1608b7f](https://github.com/googleapis/python-pubsub/commit/1608b7ffdd5b5db87e1e55fde763440ca9a4086e))
+
+## [2.10.0](https://github.com/googleapis/python-pubsub/compare/v2.9.0...v2.10.0) (2022-03-04)
+
+### Features
+
+
+* add api key support ([#571](https://github.com/googleapis/python-pubsub/issues/571)) ([cdda762](https://github.com/googleapis/python-pubsub/commit/cdda762f6d15d96f5e2d7fac975f3494dc49eaa9))
+
+
+* add exactly once delivery flag ([#577](https://github.com/googleapis/python-pubsub/issues/577)) ([d6614e2](https://github.com/googleapis/python-pubsub/commit/d6614e274328c58449e67dfc788e2e7986c0c10b))
+
+
+* add support for exactly once delivery ([#578](https://github.com/googleapis/python-pubsub/issues/578)) ([95a86fa](https://github.com/googleapis/python-pubsub/commit/95a86fa5f528701b760064f0cece0efa4e60cd44))
+
+
+* exactly-once delivery support ([#550](https://github.com/googleapis/python-pubsub/issues/550)) ([2fb6e15](https://github.com/googleapis/python-pubsub/commit/2fb6e1533192ae81dceee5c71283169a0a85a015))
+
+### Bug Fixes
+
+
+* **deps:** move libcst to extras ([#585](https://github.com/googleapis/python-pubsub/issues/585)) ([0846762](https://github.com/googleapis/python-pubsub/commit/084676243ca4afd54cda601e589b80883f9703a3))
+
+
+* refactor client classes for safer type checking ([#552](https://github.com/googleapis/python-pubsub/issues/552)) ([7f705be](https://github.com/googleapis/python-pubsub/commit/7f705beb927383f14b9d56f0341ee0de101f7c05))
+
+
+* resolve DuplicateCredentialArgs error when using credentials_file ([8ca8cf2](https://github.com/googleapis/python-pubsub/commit/8ca8cf27333baf823a1dffd081e63079f1a12625))
+
+### Samples
+
+
+* samples: create subscription with filtering enabled [#580](https://github.com/googleapis/python-pubsub/pull/580)
+
+
+* samples: handle empty response in sync pull samples [#586](https://github.com/googleapis/python-pubsub/pull/586)
+
+
+* samples: sample for receiving messages with exactly-once delivery enabled [#588](https://github.com/googleapis/python-pubsub/pull/588)
+
+
+* samples: create subscription with exactly once delivery [#592](https://github.com/googleapis/python-pubsub/pull/592)
+(https://github.com/googleapis/python-pubsub/pull/588
+
+### Documentation
+
+
+* add autogenerated code snippets ([aa3754c](https://github.com/googleapis/python-pubsub/commit/aa3754cf432bd02be2734a23a32d5b36cd216aee))
+
+
+* Docs have inconsistent default values for max_latency and max_bytes ([#572](https://github.com/googleapis/python-pubsub/issues/572)) ([d136dfd](https://github.com/googleapis/python-pubsub/commit/d136dfdb69ebeebd1411a1415f863b94d07078f0))
+
+## [2.9.0](https://www.github.com/googleapis/python-pubsub/compare/v2.8.0...v2.9.0) (2021-11-10)
+
+### Features
+
+
+* add context manager support in client ([#516](https://www.github.com/googleapis/python-pubsub/issues/516)) ([51eae67](https://www.github.com/googleapis/python-pubsub/commit/51eae67c47e2ce7d2f7620209e98df4a129801b5))
+
+
+* add support for Python 3.10 ([#518](https://www.github.com/googleapis/python-pubsub/issues/518)) ([bb25d75](https://www.github.com/googleapis/python-pubsub/commit/bb25d755d70ba19e69d8a281be65f13eb994967d))
+
+### Bug Fixes
+
+
+* add ‘dict’ annotation type to ‘request’ ([b72522a](https://www.github.com/googleapis/python-pubsub/commit/b72522a4617c4b2773fb6a5a631038791aa08300))
+
+
+* **deps:** drop packaging dependency ([290b9c5](https://www.github.com/googleapis/python-pubsub/commit/290b9c5615eaa03674b773a27b756483abd76195))
+
+
+* **deps:** require google-api-core >= 1.28.0 ([290b9c5](https://www.github.com/googleapis/python-pubsub/commit/290b9c5615eaa03674b773a27b756483abd76195))
+
+
+* improper types in pagers generation ([2ad639d](https://www.github.com/googleapis/python-pubsub/commit/2ad639d6370c7a085498595d7bd0d7eaadfff3c1))
+
+### Documentation
+
+
+* add type annotations to codebase ([#509](https://www.github.com/googleapis/python-pubsub/issues/509)) ([093cabf](https://www.github.com/googleapis/python-pubsub/commit/093cabff9f0464b1dfaa8f373b6fffbc439518de))
+
+
+* list oneofs in docstring ([290b9c5](https://www.github.com/googleapis/python-pubsub/commit/290b9c5615eaa03674b773a27b756483abd76195))
+
+## [2.8.0](https://www.github.com/googleapis/python-pubsub/compare/v2.7.1...v2.8.0) (2021-09-02)
+
+### Features
+
+
+* closed subscriber as context manager raises ([#488](https://www.github.com/googleapis/python-pubsub/issues/488)) ([a05a3f2](https://www.github.com/googleapis/python-pubsub/commit/a05a3f250cf8567ffe0d2eb3ecc45856a2bcd07c))
+
+### Documentation
+
+
+* clarify the types of Message parameters ([#486](https://www.github.com/googleapis/python-pubsub/issues/486)) ([633e91b](https://www.github.com/googleapis/python-pubsub/commit/633e91bbfc0a8f4f484089acff6812b754f40c75))
+
+## [2.7.1](https://www.github.com/googleapis/python-pubsub/compare/v2.7.0...v2.7.1) (2021-08-13)
+
+### Bug Fixes
+
+
+* remove dependency on pytz ([#472](https://www.github.com/googleapis/python-pubsub/issues/472)) ([972cc16](https://www.github.com/googleapis/python-pubsub/commit/972cc163f5a1477b37a5ab7e329faf1468637fa2))
+
+## [2.7.0](https://www.github.com/googleapis/python-pubsub/compare/v2.6.1...v2.7.0) (2021-07-24)
+
+### Features
+
+
+* Add `always_use_jwt_access`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+
+* Add method signature for `Subscriber.Pull` without the deprecated `return_immediately` field. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+
+* Add Pub/Sub topic retention fields. ([#456](https://www.github.com/googleapis/python-pubsub/issues/456)) ([911829d](https://www.github.com/googleapis/python-pubsub/commit/911829d85c6ec36a87b873cbfe34497b1a493dde))
+
+
+* Add subscription properties to streaming pull response. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+
+* Support self-signed JWT flow for service accounts. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+### Bug Fixes
+
+
+* Add async client to `%name_%version/init.py`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+
+* Disable `always_use_jwt_access`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+
+* Enable self signed JWT for gRPC. ([#458](https://www.github.com/googleapis/python-pubsub/issues/458)) ([c6e0ff6](https://www.github.com/googleapis/python-pubsub/commit/c6e0ff69faeda614aa6088af59d3420e16720d27))
+
+### Dependencies
+
+
+* Add `packaging` requirement. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+
+* Require `google-api-core >= 1.26.0`. ([1f30ef7](https://www.github.com/googleapis/python-pubsub/commit/1f30ef7f26ae1156751bc42305b1eb156115b5e5))
+
+## 2.6.1
+
+07-05-2021 10:33 PDT
+
+### Dependencies
+
+
+* Fix possible crash by requiring `grpcio >= 1.38.1`. ([#414](https://github.com/googleapis/python-pubsub/issues/414)) ([7037a28](https://github.com/googleapis/python-pubsub/pull/435/commits/7037a28090aa4efa01808231721716bca80bb0b7))
+
+### Documentation
+
+
+* Adjust samples for publishing with error handler and flow control. ([#433](https://github.com/googleapis/python-pubsub/pull/433))
+
+### Internal / Testing Changes
+
+
+* Fix flaky sync pull sample test. ([#434](https://github.com/googleapis/python-pubsub/pull/434))
+
+
+* Mitigate flaky snippets tests. ([#432](https://github.com/googleapis/python-pubsub/pull/432))
+
+## [2.6.0](https://www.github.com/googleapis/python-pubsub/compare/v2.5.0...v2.6.0) (2021-06-17)
+
+### Features
+
+
+* support customizable retry and timeout settings on the publisher client ([#299](https://www.github.com/googleapis/python-pubsub/issues/299)) ([7597604](https://www.github.com/googleapis/python-pubsub/commit/7597604b41fa3a1e9bf34addc35c8647dde007cc))
+
+### Bug Fixes
+
+
+* ACK deadline set for received messages can be too low ([#416](https://www.github.com/googleapis/python-pubsub/issues/416)) ([e907f6e](https://www.github.com/googleapis/python-pubsub/commit/e907f6e05f59f64a3b08df3304e92ec960997be6))
+
+
+* threads can skip the line in publisher flow controller ([#422](https://www.github.com/googleapis/python-pubsub/issues/422)) ([ef89f55](https://www.github.com/googleapis/python-pubsub/commit/ef89f55a41044e9ad26b91132b4b1be9c7b2c127))
+
+### Documentation
+
+
+* block until the streaming pull shuts down ([#424](https://www.github.com/googleapis/python-pubsub/issues/424)) ([d0d0b70](https://www.github.com/googleapis/python-pubsub/commit/d0d0b704642df8dee893d3f585aeb666e19696fb))
+
+
+* explain that future.cancel() is non-blocking ([#420](https://www.github.com/googleapis/python-pubsub/issues/420)) ([c825789](https://www.github.com/googleapis/python-pubsub/commit/c825789bdff310f44cbb132a723e99d1e6331d8f))
+
+## [2.5.0](https://www.github.com/googleapis/python-pubsub/compare/v2.4.2...v2.5.0) (2021-05-18)
+
+### Features
+
+
+* Make publish futures compatible with `concurrent.futures.as_completed()`. ([#397](https://www.github.com/googleapis/python-pubsub/issues/397)) ([e29a2c0](https://www.github.com/googleapis/python-pubsub/commit/e29a2c0ac6c5d2ebf2311646e552a02f184cfedc))
+
+### Bug Fixes
+
+
+* Scheduler errors when executor in shutdown. ([#399](https://www.github.com/googleapis/python-pubsub/issues/399)) ([39a83d3](https://www.github.com/googleapis/python-pubsub/commit/39a83d3eef196e88478ad8362201a2ab12e9f681))
+
+## 2.4.2
+
+05-06-2021 23:50 PDT
+
+### Implementation Changes
+
+
+* Fix memory leak when publishing messages. ([#406](https://github.com/googleapis/python-pubsub/pull/406))
+
+
+* Do not crash if distribution cannot be found when extracting semantic version. ([#393](https://github.com/googleapis/python-pubsub/pull/393))
+
+
+* Emit a warning if `return_immediately` is set with synchronous pull. ([#355](https://github.com/googleapis/python-pubsub/pull/355))
+
+
+* Regenerate GAPIC layer with latest changes, use explicit default timeouts. ([#345](https://github.com/googleapis/python-pubsub/pull/345))
+
+### Documentation
+
+
+* Add additional info on `use_legacy_flow_control` parameter. ([#301](https://github.com/googleapis/python-pubsub/pull/301))
+
+
+* Remove EXPERIMENTAL tag for ordering keys in `publisher/client.py`. ([#324](https://github.com/googleapis/python-pubsub/pull/324))
+
+
+* Fix `create_topic()` call in README. ([#360](https://github.com/googleapis/python-pubsub/pull/360))
+
+
+* Generate PyPI token in secrets manager, fix spacing in docs (via synth). ([#384](https://github.com/googleapis/python-pubsub/pull/384))
+
+
+* Add `SECURITY.md`. ([#401](https://github.com/googleapis/python-pubsub/pull/401))
+
+### Internal / Testing Changes
+
+
+* Require 100% unit test coverage (via synth). ([#359](https://github.com/googleapis/python-pubsub/pull/359))
+
+
+* Bump test coverage to 100%. ([#364](https://github.com/googleapis/python-pubsub/pull/364))
+
+
+* Fix streaming pull close unit test flakiness. ([#361](https://github.com/googleapis/python-pubsub/pull/361))
+
+
+* Pass explicit credentials in all unit tests creating clients. ([#369](https://github.com/googleapis/python-pubsub/pull/369))
+
+
+* Fix flaky test for blocking pull shutdown. ([#378](https://github.com/googleapis/python-pubsub/pull/378))
+
+
+* Add missing licence header. ([#377](https://github.com/googleapis/python-pubsub/pull/377))
+
+## [2.4.1](https://www.github.com/googleapis/python-pubsub/compare/v2.4.0...v2.4.1) (2021-03-30)
+
+### Bug Fixes
+
+
+* Move `await_msg_callbacks` flag to `subscribe()` method, fixing a regression in Pub/Sub Lite client.
+([#320](https://www.github.com/googleapis/python-pubsub/issues/320)) ([d40d027](https://www.github.com/googleapis/python-pubsub/commit/d40d02713c8c189937ae5c21d099b88a3131a59f))
+
+
+* SSL error when using the client with the emulator. ([#297](https://www.github.com/googleapis/python-pubsub/issues/297)) ([83db672](https://www.github.com/googleapis/python-pubsub/commit/83db67239d3521457138699109f766d574a0a2c4))
+
+### Implementation Changes
+
+
+* (samples) Bump the max_time to 10 minutes for a flaky test. ([#311](https://www.github.com/googleapis/python-pubsub/issues/311)) ([e2678d4](https://www.github.com/googleapis/python-pubsub/commit/e2678d47c08e6b03782d2d744a4e630b933fdd51)), closes [#291](https://www.github.com/googleapis/python-pubsub/issues/291)
+
+
+* (samples) Mark delivery attempts test as flaky. ([#326](https://www.github.com/googleapis/python-pubsub/issues/326)) ([5a97ef1](https://www.github.com/googleapis/python-pubsub/commit/5a97ef1bb7512fe814a8f72a43b3e9698434cd8d))
+
+
+* (samples) Mitigate flakiness in subscriber_tests. ([#304](https://www.github.com/googleapis/python-pubsub/issues/304)) ([271a385](https://www.github.com/googleapis/python-pubsub/commit/271a3856d835967f18f6becdae5ad53d585d0ccf))
+
+
+* (samples) Retry `InternalServerError` in dead letter policy test. ([#329](https://www.github.com/googleapis/python-pubsub/issues/329)) ([34c9b11](https://www.github.com/googleapis/python-pubsub/commit/34c9b11ae697c280f32642c3101b7f7da971f589)), closes [#321](https://www.github.com/googleapis/python-pubsub/issues/321)
+
+### Documentation
+
+
+* Remove EXPERIMENTAL tag for ordering keys in `types.py`. ([#323](https://www.github.com/googleapis/python-pubsub/issues/323)) ([659cd7a](https://www.github.com/googleapis/python-pubsub/commit/659cd7ae2784245d4217fbc722dac04bd3222d32))
+
+
+* Remove EXPERIMENTAL tag from `Schema` service (via synth). ([#307](https://www.github.com/googleapis/python-pubsub/issues/307)) ([ad85202](https://www.github.com/googleapis/python-pubsub/commit/ad852028836520db779c5cc33689ffd7e5458a7d))
+
+## 2.4.0
+
+02-22-2021 05:02 PST
+
+### Implementation Changes
+
+### New Features
+
+
+* Add graceful streaming pull shutdown. ([#292](https://github.com/googleapis/python-pubsub/pull/292))
+
+### Documentation
+
+
+* Update samples with using the subscriber client as a context manager. ([#254](https://github.com/googleapis/python-pubsub/pull/254))
+
+## [2.3.0](https://www.github.com/googleapis/python-pubsub/compare/v2.2.0...v2.3.0) (2021-02-08)
+
+### Features
+
+
+* surface SchemaServiceClient in google.cloud.pubsub ([#281](https://www.github.com/googleapis/python-pubsub/issues/281)) ([8751bcc](https://www.github.com/googleapis/python-pubsub/commit/8751bcc5eb782df55769b48253629a3bde3d4661))
+
+### Bug Fixes
+
+
+* client version missing from the user agent header ([#275](https://www.github.com/googleapis/python-pubsub/issues/275)) ([b112f4f](https://www.github.com/googleapis/python-pubsub/commit/b112f4fcbf6f2bce8dcf37871bdc540b11f54fe3))
+
+
+* Don’t open the google.cloud package by adding pubsub.py ([#269](https://www.github.com/googleapis/python-pubsub/issues/269)) ([542d79d](https://www.github.com/googleapis/python-pubsub/commit/542d79d7c5fb7403016150ba477485756cd4097b))
+
+
+* flaky samples tests ([#263](https://www.github.com/googleapis/python-pubsub/issues/263)) ([3d6a29d](https://www.github.com/googleapis/python-pubsub/commit/3d6a29de07cc09be663c90a3333f4cd33633994f))
+
+
+* Modify synth.py to update grpc transport options ([#266](https://www.github.com/googleapis/python-pubsub/issues/266)) ([41dcd30](https://www.github.com/googleapis/python-pubsub/commit/41dcd30636168f3dd1248f1d99170d531fc9bcb8))
+
+
+* pass anonymous credentials for emulator ([#250](https://www.github.com/googleapis/python-pubsub/issues/250)) ([8eed8e1](https://www.github.com/googleapis/python-pubsub/commit/8eed8e16019510dc8b20fb6b009d61a7ac532d26))
+
+
+* remove grpc send/recieve limits ([#259](https://www.github.com/googleapis/python-pubsub/issues/259)) ([fd2840c](https://www.github.com/googleapis/python-pubsub/commit/fd2840c10f92b03da7f4b40ac69c602220757c0a))
+
+## [2.2.0](https://www.github.com/googleapis/python-pubsub/compare/v2.1.0...v2.2.0) (2020-11-16)
+
+### Features
+
+
+* Add dead lettering max delivery attempts argument ([#236](https://www.github.com/googleapis/python-pubsub/issues/236)) ([7687ae5](https://www.github.com/googleapis/python-pubsub/commit/7687ae500bdb9c76e3ffb23302b4f32dc9627d81))
+
+
+* Enable server side flow control by default with the option to turn it off ([#231](https://www.github.com/googleapis/python-pubsub/issues/231)) ([94d738c](https://www.github.com/googleapis/python-pubsub/commit/94d738c07c6404a152c6729f5ba4b106b1fe9355))
+
+### Bug Fixes
+
+
+* fix mtls issue in handwritten layer ([#226](https://www.github.com/googleapis/python-pubsub/issues/226)) ([09a409c](https://www.github.com/googleapis/python-pubsub/commit/09a409c6240a74dcb46d8f3f86d4fb95a52274a7))
+
+
+* make fixup script consistent with migration docs ([#208](https://www.github.com/googleapis/python-pubsub/issues/208)) ([b64e218](https://www.github.com/googleapis/python-pubsub/commit/b64e2187ab0810437575580d6ddb5315ff60e274))
+
+### Documentation
+
+
+* document potentially unexpected blocking behavior of publish() method ([#214](https://www.github.com/googleapis/python-pubsub/issues/214)) ([b6d9bd7](https://www.github.com/googleapis/python-pubsub/commit/b6d9bd7c38d4fe597c25b7b5869fd4a1259c7687))
+
+
+* fix get topic_path in subscriber sample ([#210](https://www.github.com/googleapis/python-pubsub/issues/210)) ([7228f6c](https://www.github.com/googleapis/python-pubsub/commit/7228f6c9a4c050bf22bb4bc3582b89b04eaa8702))
+
+## 2.1.0
+
+09-21-2020 02:19 PDT
+
+### Implementation Changes
+
+
+* Convert all RPC error types to exceptions. ([#163](https://github.com/googleapis/python-pubsub/issues/163)) ([#170](https://github.com/googleapis/python-pubsub/pull/170))
+
+
+* Pass client options to publisher and subscriber clients. ([#166](https://github.com/googleapis/python-pubsub/issues/166)) ([#190](https://github.com/googleapis/python-pubsub/pull/190))
+
+### New Features
+
+
+* Regenerate the client lib to pick new mtls env (via synth). ([#197](https://github.com/googleapis/python-pubsub/pull/197))
+
+### Documentation
+
+
+* Add subscription detachment sample. ([#152](https://github.com/googleapis/python-pubsub/pull/152))
+
+
+* Use new call syntax in subscriber docs. ([#198](https://github.com/googleapis/python-pubsub/issues/198)) ([#203](https://github.com/googleapis/python-pubsub/pull/203))
+
+### Internal / Testing Changes
+
+
+* Update CODEOWNERS. ([#193](https://github.com/googleapis/python-pubsub/pull/193))
+
+## 2.0.0
+
+09-11-2020 05:03 PDT
+
+### Implementation Changes
+
+
+* Transition the library to microgenerator. ([#158](https://github.com/googleapis/python-pubsub/pull/158))
+This is a **breaking change** that introduces several **method signature changes** and **drops support
+for Python 2.7 and 3.5**.
+
+### Documentation
+
+
+* Add samples for using ordering keys. ([#156](https://github.com/googleapis/python-pubsub/pull/156))
+
+
+* Remove extra white space in delivery attempt sample. ([#159](https://github.com/googleapis/python-pubsub/pull/159))
+
+### Internal / Testing Changes
+
+
+* Fix flaky sequencer unit tests. ([#187](https://github.com/googleapis/python-pubsub/pull/187))
+
+## [1.7.0](https://www.github.com/googleapis/python-pubsub/compare/v1.6.1...v1.7.0) (2020-07-13)
+
+This is the last release that supports Python 2.7 and 3.5.
+
+### New Features
+
+
+* Add support for server-side flow control. ([#143](https://github.com/googleapis/python-pubsub/pull/143)) ([04e261c](https://www.github.com/googleapis/python-pubsub/commit/04e261c602a2919cc75b3efa3dab099fb2cf704c))
+
+### Dependencies
+
+
+* Update samples dependency `google-cloud-pubsub` to `v1.6.1`. ([#144](https://github.com/googleapis/python-pubsub/pull/144)) ([1cb6746](https://github.com/googleapis/python-pubsub/commit/1cb6746b00ebb23dbf1663bae301b32c3fc65a88))
+
+### Documentation
+
+
+* Add pubsub/cloud-client samples from the common samples repo (with commit history). ([#151](https://github.com/googleapis/python-pubsub/pull/151))
+
+
+* Add flow control section to publish overview. ([#129](https://github.com/googleapis/python-pubsub/pull/129)) ([acc19eb](https://www.github.com/googleapis/python-pubsub/commit/acc19eb048eef067d9818ef3e310b165d9c6307e))
+
+
+* Add a link to Pub/Sub filtering language public documentation to `pubsub.proto`. ([#121](https://github.com/googleapis/python-pubsub/pull/121)) ([8802d81](https://www.github.com/googleapis/python-pubsub/commit/8802d8126247f22e26057e68a42f5b5a82dcbf0d))
+
+## [1.6.1](https://www.github.com/googleapis/python-pubsub/compare/v1.6.0...v1.6.1) (2020-06-30)
+
+### Documentation
+
+
+* added Python2 sunset notice (synth) ([#140](https://www.github.com/googleapis/python-pubsub/issues/140)) ([c8f6378](https://www.github.com/googleapis/python-pubsub/commit/c8f63788636c2e3436c8ce6a01ef3b59e3df772a))
+
+
+* explain how to nack a sync pull message ([#123](https://www.github.com/googleapis/python-pubsub/issues/123)) ([f2eec65](https://www.github.com/googleapis/python-pubsub/commit/f2eec65cec43066ba7a2d1d45efa979e6b7add4f))
+
+## [1.6.0](https://www.github.com/googleapis/python-pubsub/compare/v1.5.0...v1.6.0) (2020-06-09)
+
+### Features
+
+
+* Add flow control for message publishing ([#96](https://www.github.com/googleapis/python-pubsub/issues/96)) ([06085c4](https://www.github.com/googleapis/python-pubsub/commit/06085c4083b9dccdd50383257799904510bbf3a0))
+
+### Bug Fixes
+
+
+* Fix PubSub incompatibility with api-core 1.17.0+ ([#103](https://www.github.com/googleapis/python-pubsub/issues/103)) ([c02060f](https://www.github.com/googleapis/python-pubsub/commit/c02060fbbe6e2ca4664bee08d2de10665d41dc0b))
+
+### Documentation
+
+
+* Clarify that Schedulers shouldn’t be used with multiple SubscriberClients ([#100](https://github.com/googleapis/python-pubsub/pull/100)) ([cf9e87c](https://github.com/googleapis/python-pubsub/commit/cf9e87c80c0771f3fa6ef784a8d76cb760ad37ef))
+
+
+* Fix update subscription/snapshot/topic samples ([#113](https://github.com/googleapis/python-pubsub/pull/113)) ([e62c38b](https://github.com/googleapis/python-pubsub/commit/e62c38bb33de2434e32f866979de769382dea34a))
+
+### Internal / Testing Changes
+
+
+* Re-generated service implementaton using synth: removed experimental notes from the RetryPolicy and filtering features in anticipation of GA, added DetachSubscription (experimental) ([#114](https://github.com/googleapis/python-pubsub/pull/114)) ([0132a46](https://github.com/googleapis/python-pubsub/commit/0132a4680e0727ce45d5e27d98ffc9f3541a0962))
+
+
+* Incorporate will_accept() checks into publish() ([#108](https://github.com/googleapis/python-pubsub/pull/108)) ([6c7677e](https://github.com/googleapis/python-pubsub/commit/6c7677ecb259672bbb9b6f7646919e602c698570))
+
+## [1.5.0](https://www.github.com/googleapis/python-pubsub/compare/v1.4.3...v1.5.0) (2020-05-04)
+
+### Features
+
+
+* add methods for listing snapshots (via synth) ([#66](https://www.github.com/googleapis/python-pubsub/issues/66)) ([4ce898e](https://www.github.com/googleapis/python-pubsub/commit/4ce898e80eeb16b18d1ee29c678ade149804d186))
+
+
+* send client id with StreamingPullRequest ([#58](https://www.github.com/googleapis/python-pubsub/issues/58)) ([9f8acfa](https://www.github.com/googleapis/python-pubsub/commit/9f8acfacfbe93224f59439bb51a17fc28b06c22a)), closes [#62](https://www.github.com/googleapis/python-pubsub/issues/62)
+
+## [1.4.3](https://www.github.com/googleapis/python-pubsub/compare/v1.4.2...v1.4.3) (2020-04-16)
+
+### Bug Fixes
+
+
+* fix docs warnings in Sphinx 3.0+ ([#70](https://www.github.com/googleapis/python-pubsub/issues/70)) ([21e761e](https://www.github.com/googleapis/python-pubsub/commit/21e761ee89a4c03e105dc9cddbab0a34be9a9fda))
+
+
+* restrict api-core dependency to < 1.17.0 ([#76](https://www.github.com/googleapis/python-pubsub/issues/76)) ([191b051](https://www.github.com/googleapis/python-pubsub/commit/191b0516335f5c60828a818ba79e99d6c68aa7bd))
+
+## [1.4.2](https://www.github.com/googleapis/python-pubsub/compare/v1.4.1...v1.4.2) (2020-03-25)
+
+### Bug Fixes
+
+
+* update generated retry timings for publish and pull rpcs via synth ([#43](https://www.github.com/googleapis/python-pubsub/issues/43)) ([4f7fe85](https://www.github.com/googleapis/python-pubsub/commit/4f7fe85618d811fea94cb46b5dc758aa78c328a8))
+
+
+* use client_options.api_endpoint parameter instead of ignoring it ([#59](https://www.github.com/googleapis/python-pubsub/issues/59)) ([56b8d7b](https://www.github.com/googleapis/python-pubsub/commit/56b8d7b046a495ce2ce59bebdd354385147a5013)), closes [#61](https://www.github.com/googleapis/python-pubsub/issues/61)
+
+## [1.4.1](https://www.github.com/googleapis/python-pubsub/compare/v1.4.0...v1.4.1) (2020-03-23)
+
+### Bug Fixes
+
+
+* Don’t assert on unordered publishes after publish error. ([#49](https://www.github.com/googleapis/python-pubsub/issues/49)) ([ea19ce6](https://www.github.com/googleapis/python-pubsub/commit/ea19ce616f6961e8993b72cd2921f7f3e61541f9))
+
+## [1.4.0](https://www.github.com/googleapis/python-pubsub/compare/v1.3.1...v1.4.0) (2020-03-06)
+
+### Features
+
+
+* **pubsub:** implement max_duration_per_lease_extension option ([#38](https://www.github.com/googleapis/python-pubsub/issues/38)) ([d911a2d](https://www.github.com/googleapis/python-pubsub/commit/d911a2dc8edf3c348ad3f128368b30e32dbc449e))
+
+## [1.3.1](https://www.github.com/googleapis/python-pubsub/compare/v1.3.0...v1.3.1) (2020-02-28)
+
+### Bug Fixes
+
+
+* shutdown error on streaming pull callback error ([#40](https://www.github.com/googleapis/python-pubsub/issues/40)) ([552539e](https://www.github.com/googleapis/python-pubsub/commit/552539e7beb30833c39dd29bfcb0183a07895f97))
+
+## [1.3.0](https://www.github.com/googleapis/python-pubsub/compare/v1.2.0...v1.3.0) (2020-02-20)
+
+### Features
+
+
+* **pubsub:** ordering keys ([#26](https://www.github.com/googleapis/python-pubsub/issues/26)) ([cc3093a](https://www.github.com/googleapis/python-pubsub/commit/cc3093a2c0304259bc374bc2eeec9630e4a11a5e))
+
+
+* add context manager capability to subscriber ([#32](https://www.github.com/googleapis/python-pubsub/issues/32)) ([b58d0d8](https://www.github.com/googleapis/python-pubsub/commit/b58d0d8e404c0a085b89d3407e6640651e81568c))
+
+## [1.2.0](https://www.github.com/googleapis/python-pubsub/compare/v1.1.0...v1.2.0) (2020-02-05)
+
+### Features
+
+
+* **pubsub:** add delivery attempt property to message object received by user code ([#10205](https://www.github.com/googleapis/google-cloud-python/issues/10205)) ([a0937c1](https://www.github.com/googleapis/python-pubsub/commit/a0937c13107b92271913de579b60f24b2aaac177))
+
+
+* add `StreamingPullRequest.client_id` field (via synth) ([199d56a](https://www.github.com/googleapis/python-pubsub/commit/199d56a939bb6244f67138f843dafdd80721f0d3))
+
+### Bug Fixes
+
+
+* **pubsub:** handle None in on response callback ([#9982](https://www.github.com/googleapis/google-cloud-python/issues/9982)) ([6596c4b](https://www.github.com/googleapis/python-pubsub/commit/6596c4bae5526d82f5c1b5e0c243b2883404d51f))
+
+
+* replace unsafe six.PY3 with PY2 for better future compatibility with Python 4 ([#10081](https://www.github.com/googleapis/google-cloud-python/issues/10081)) ([975c1ac](https://www.github.com/googleapis/python-pubsub/commit/975c1ac2cfdac0ce4403c0b56ad19f2ee7241f1a))
+
+## 1.1.0
+
+12-09-2019 18:51 PST
+
+### Implementation Changes
+
+
+* Update client configurations (via synth). ([#9784](https://github.com/googleapis/google-cloud-python/pull/9784))
+
+
+* Include request overhead when computing publish batch size overflow. ([#9911](https://github.com/googleapis/google-cloud-python/pull/9911))
+
+
+* Split large (mod)ACK requests into smaller ones. ([#9594](https://github.com/googleapis/google-cloud-python/pull/9594))
+
+
+* Fix messages delivered multiple times despite a long ACK deadline. ([#9525](https://github.com/googleapis/google-cloud-python/pull/9525))
+
+
+* Update batching and flow control parameters to be same as the other client libraries. ([#9597](https://github.com/googleapis/google-cloud-python/pull/9597))
+
+
+* Add `StreamingPullManager._should_terminate`. ([#9335](https://github.com/googleapis/google-cloud-python/pull/9335))
+
+### New Features
+
+
+* Add stop method. ([#9365](https://github.com/googleapis/google-cloud-python/pull/9365))
+
+### Dependencies
+
+
+* Add Python 2 sunset banner to documentation. ([#9036](https://github.com/googleapis/google-cloud-python/pull/9036))
+
+### Documentation
+
+
+* Change spacing in docs templates (via synth). ([#9759](https://github.com/googleapis/google-cloud-python/pull/9759))
+
+### Internal / Testing Changes
+
+
+* Refactor fake leaser test helper. ([#9632](https://github.com/googleapis/google-cloud-python/pull/9632))
+
+
+* Add subscriber role test for streaming. ([#9507](https://github.com/googleapis/google-cloud-python/pull/9507))
+
+## 1.0.2
+
+09-30-2019 11:57 PDT
+
+### Implementation Changes
+
+
+* Streaming pull shouldn’t need `subscriptions.get` permission ([#9360](https://github.com/googleapis/google-cloud-python/pull/9360)).
+
+## 1.0.1
+
+09-27-2019 07:01 PDT
+
+### Implementation Changes
+
+
+* Set default stream ACK deadline to subscriptions’. ([#9268](https://github.com/googleapis/google-cloud-python/pull/9268))
+
+### Documentation
+
+
+* Fix intersphinx reference to requests. ([#9294](https://github.com/googleapis/google-cloud-python/pull/9294))
+
+
+* Link to correct TimeoutError in futures docs. ([#9216](https://github.com/googleapis/google-cloud-python/pull/9216))
+
+### Internal / Testing Changes
+
+
+* Adjust messaging RPC timeout settings (via synth). [#9279](https://github.com/googleapis/google-cloud-python/pull/9279)
+
+## 1.0.0
+
+08-29-2019 09:27 PDT
+
+### Implementation Changes
+
+
+* Add ‘ReceivedMessage.delivery_attempt’ field (via synth). ([#9098](https://github.com/googleapis/google-cloud-python/pull/9098))
+
+
+* Remove send/recv msg size limit, update docstrings (via synth). ([#8964](https://github.com/googleapis/google-cloud-python/pull/8964))
+
+### Documentation
+
+
+* Update docstrings for client kwargs and fix return types uris ([#9037](https://github.com/googleapis/google-cloud-python/pull/9037))
+
+
+* Remove CI for gh-pages, use googleapis.dev for api_core refs. ([#9085](https://github.com/googleapis/google-cloud-python/pull/9085))
+
+
+* Remove compatability badges from READMEs. ([#9035](https://github.com/googleapis/google-cloud-python/pull/9035))
+
+### Internal / Testing Changes
+
+
+* Add dead-letter-policy field in preparation for its implementation (via synth) ([#9078](https://github.com/googleapis/google-cloud-python/pull/9078))
+
+## 0.45.0
+
+07-31-2019 02:03 PDT
+
+### Implementation Changes
+
+
+* Remove deprecated methods and settings ([#8836](https://github.com/googleapis/google-cloud-python/pull/8836))
+
+### Documentation
+
+
+* Use double backticks for ReST correctness. ([#8829](https://github.com/googleapis/google-cloud-python/pull/8829))
+
+
+* Update intersphinx mapping for requests. ([#8805](https://github.com/googleapis/google-cloud-python/pull/8805))
+
+## 0.44.0
+
+07-29-2019 04:28 PDT
+
+### Implementation Changes
+
+
+* PubSub: Deprecate several FlowControl settings and things in Message class ([#8796](https://github.com/googleapis/google-cloud-python/pull/8796))
+
+### Documentation
+
+
+* Pub/Sub: document regional endpoint ([#8789](https://github.com/googleapis/google-cloud-python/pull/8789))
+
+## 0.43.0
+
+07-24-2019 17:13 PDT
+
+### Implementation Changes
+
+
+* Accomodate new location of ‘IAMPolicyStub’ (via synth). ([#8680](https://github.com/googleapis/google-cloud-python/pull/8680))
+
+
+* Use kwargs in test_subscriber_client ([#8414](https://github.com/googleapis/google-cloud-python/pull/8414))
+
+### New Features
+
+
+* Add `options_` argument to clients’ `get_iam_policy`; pin black version (via synth). ([#8657](https://github.com/googleapis/google-cloud-python/pull/8657))
+
+
+* Add ‘client_options’ support, update list method docstrings (via synth). ([#8518](https://github.com/googleapis/google-cloud-python/pull/8518))
+
+### Dependencies
+
+
+* Bump minimum version for google-api-core to 1.14.0. ([#8709](https://github.com/googleapis/google-cloud-python/pull/8709))
+
+
+* Update pin for ‘grpc-google-iam-v1’ to 0.12.3+. ([#8647](https://github.com/googleapis/google-cloud-python/pull/8647))
+
+### Documentation
+
+
+* Link to googleapis.dev documentation in READMEs. ([#8705](https://github.com/googleapis/google-cloud-python/pull/8705))
+
+
+* Add compatibility check badges to READMEs. ([#8288](https://github.com/googleapis/google-cloud-python/pull/8288))
+
+
+* Fix typo in publisher index. ([#8619](https://github.com/googleapis/google-cloud-python/pull/8619))
+
+
+* Document how to choose the PubSub auth method ([#8429](https://github.com/googleapis/google-cloud-python/pull/8429))
+
+
+* Document different PuSub received message types ([#8468](https://github.com/googleapis/google-cloud-python/pull/8468))
+
+
+* PubSub: Document batch settings, make synth operations idempotent ([#8448](https://github.com/googleapis/google-cloud-python/pull/8448))
+
+
+* Add custom docstrings for FlowControl enum and values (via synth). ([#8426](https://github.com/googleapis/google-cloud-python/pull/8426))
+
+### Internal / Testing Changes
+
+
+* Add docs job to publish to googleapis.dev. ([#8464](https://github.com/googleapis/google-cloud-python/pull/8464))
+
+
+* Add system tests for PubSub clients ([#8277](https://github.com/googleapis/google-cloud-python/pull/8277))
+
+## 0.42.1
+
+06-18-2019 15:14 PDT
+
+### Implementation Changes
+
+
+* Increase the minimum allowed version for api core. ([#8419](https://github.com/googleapis/google-cloud-python/pull/8419))
+
+
+* Allow kwargs to be passed to create_channel. ([#8399](https://github.com/googleapis/google-cloud-python/pull/8399))
+
+## 0.42.0
+
+06-18-2019 11:32 PDT
+
+### Implementation Changes
+
+
+* Core: Mitigate busy reopen loop in ResumableBidiRpc consuming 100% CPU ([#8193](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8193))
+
+
+* Pub/Sub: Increase initial_rpc_timeout for messaging (via synth). ([#8219](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8219))
+
+
+* PubSub: Release the state lock before calling the publish api ([#8234](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8234))
+
+
+* Pub/Sub: Expose publish retry settings ([#8231](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8231))
+
+
+* Prevent unhandled background error on SPM shutdown ([#8111](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8111))
+
+
+* Update timeouts, blacken noxfile.py, setup.py (via synth). ([#8128](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8128))
+
+
+* PubSub: Fix streaming pull incorrectly handling FlowControl max_messages setting ([#7948](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7948))
+
+### Documentation
+
+
+* Document PubSub FlowControl settings ([#8293](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8293))
+
+
+* Replace readthedocs links with links to github docs. ([#8291](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8291))
+
+
+* Pub/Sub: surface publish future in documentation ([#8229](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8229))
+
+
+* Pubsub: Separate subscriber and publish future documentation. ([#8205](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8205))
+
+
+* Drop mention of long-removed ‘policy’ object. ([#8081](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8081))
+
+### Internal / Testing Changes
+
+
+* Pub/Sub: staticmethod check ([#8091](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8091))
+
+
+* Add empty lines (via synth). ([#8067](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/8067))
+
+## 0.41.0
+
+05-15-2019 13:57 PDT
+
+### New Features
+
+
+* Add `kms_key_name` arg to `create_topic`; remove BETA warnings (via synth). ([#7936](https://github.com/googleapis/google-cloud-python/pull/7936))
+
+
+* Add message ordering (via synth). ([#7551](https://github.com/googleapis/google-cloud-python/pull/7551))
+
+### Implementation Changes
+
+
+* Propagate subscribe callback errors to main thread ([#7954](https://github.com/googleapis/google-cloud-python/pull/7954))
+
+
+* Fix pubsub Streaming Pull shutdown on RetryError ([#7863](https://github.com/googleapis/google-cloud-python/pull/7863))
+
+
+* Make PubSub subscriber Scheduler inherit from ABC ([#7690](https://github.com/googleapis/google-cloud-python/pull/7690))
+
+
+* Add routing header to method metadata (via synth). ([#7623](https://github.com/googleapis/google-cloud-python/pull/7623))
+
+### Internal / Testing Changes
+
+
+* Remove classifier for Python 3.4 for end-of-life. ([#7535](https://github.com/googleapis/google-cloud-python/pull/7535))
+
+
+* Add nox session `docs` (via synth). ([#7778](https://github.com/googleapis/google-cloud-python/pull/7778))
+
+
+* Pub/Sub (nit): wrong var name in sample ([#7705](https://github.com/googleapis/google-cloud-python/pull/7705))
+
+## 0.40.0
+
+03-15-2019 14:09 PDT
+
+### Implementation Changes
+
+
+* Propagate ‘RetryError’ in ‘PublisherClient.publish’. ([#7071](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7071))
+
+
+* Protoc-generated serialization update.. ([#7091](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7091))
+
+### New Features
+
+
+* Add ‘authentication_method’ to ‘PushConfig’ (via synth). ([#7512](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7512))
+
+
+* Add protos as an artifact to library ([#7205](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7205))
+
+
+* Pub/sub: pass transport w/ custom channel to GAPIC API clients. ([#7008](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7008))
+
+### Dependencies
+
+### Documentation
+
+
+* Updated client library documentation URLs. ([#7307](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7307))
+
+
+* Update copyright headers
+
+
+* Fix broken docstring cross-reference links. ([#7132](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7132))
+
+
+* Docstring changes from updates to .proto files. ([#7054](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/7054))
+
+
+* Pick up stub docstring fix in GAPIC generator. ([#6978](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6978))
+
+### Internal / Testing Changes
+
+
+* Copy proto files alongside protoc versions.
+
+## 0.39.1
+
+12-17-2018 16:57 PST
+
+### Implementation Changes
+
+
+* Initialize `StreamingPullFuture._cancelled` as True. ([#6901](https://github.com/googleapis/google-cloud-python/pull/6901))
+
+
+* Import `iam.policy` from `google.api_core`. ([#6741](https://github.com/googleapis/google-cloud-python/pull/6741))
+
+### Documentation
+
+
+* Document Python 2 deprecation ([#6910](https://github.com/googleapis/google-cloud-python/pull/6910))
+
+
+* Emphasize that returned futures may differ from stdlib futures. ([#6875](https://github.com/googleapis/google-cloud-python/pull/6875))
+
+### Internal / Testing Changes
+
+
+* Add baseline for synth.metadata
+
+
+* Update noxfile.
+
+
+* blacken all gen’d libs ([#6792](https://github.com/googleapis/google-cloud-python/pull/6792))
+
+
+* omit local deps ([#6701](https://github.com/googleapis/google-cloud-python/pull/6701))
+
+
+* Run black at end of synth.py ([#6698](https://github.com/googleapis/google-cloud-python/pull/6698))
+
+
+* Run Black on Generated libraries ([#6666](https://github.com/googleapis/google-cloud-python/pull/6666))
+
+
+* Add templates for flake8, coveragerc, noxfile, and black. ([#6642](https://github.com/googleapis/google-cloud-python/pull/6642))
+
+## 0.39.0
+
+11-27-2018 13:32 PST
+
+### Implementation Changes
+
+
+* Pick up fixes to GAPIC generator. ([#6503](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6503))
+
+
+* Override client classmethod factories inherited from GAPIC. ([#6453](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6453))
+
+
+* Fix imports for hand-written client docstring examples. ([#6345](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6345))
+
+
+* Fix path for patch of ‘bidi’ elements. ([#6243](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6243))
+
+
+* Move bidi to api-core. ([#6211](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6211))
+
+
+* Re-generate library using pubsub/synth.py ([#6059](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6059))
+
+
+* Re-generate library using pubsub/synth.py ([#5978](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5978))
+
+### New Features
+
+
+* Add ‘expiration_policy’ to subscriber client. ([#6223](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6223))
+
+### Dependencies
+
+
+* Bump minimum ‘api_core’ version for all GAPIC libs to 1.4.1. ([#6391](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6391))
+
+
+* Update IAM version in dependencies. ([#6362](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6362))
+
+
+* Bump minimum ‘api_core’ version to ‘1.4.1’. ([#6134](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6134))
+
+### Documentation
+
+
+* Fix client_info bug, update docstrings. ([#6418](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6418))
+
+
+* Fix docstring reference to wrong future class. ([#6382](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6382))
+
+
+* Normalize use of support level badges. ([#6159](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6159))
+
+
+* Update subscriber example in README to current patterns. ([#6194](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6194))
+
+
+* Prep pubsub docs for repo split. ([#6001](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6001))
+
+### Internal / Testing Changes
+
+
+* Fix error from new flake8 version. ([#6346](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6346))
+
+
+* Use new Nox. ([#6175](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/6175))
+
+## 0.38.0
+
+### Implementation Changes
+
+
+* Fix race condition in recv()’s usage of self.call. ([#5935](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5935))
+
+
+* Re-generate the underlying library from protos. ([#5953](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5953))
+
+
+* Change ‘BatchSettings.max_bytes’ default. ([#5899](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5899))
+
+
+* Fix race condition where pending Ack IDs can be modified by another thread. ([#5929](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5929))
+
+### Internal / Testing Changes
+
+
+* Nox: use inplace installs ([#5865](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/5865))
+
+## 0.37.2
+
+### Implementation Changes
+
+
+* Fix classmethod wrapping (#5826)
+
+### Documentation
+
+
+* Fix Sphinx rendering for publisher client. (#5822)
+
+### Internal / Testing Changes
+
+
+* Re-generate library, removing obsolete synth modifications. (#5825)
+
+
+* Add test for testing invoking a wrapped class method on the class itself (#5828)
+
+## 0.37.1
+
+### Implementation Changes
+
+
+* Make get_initial_request more resilient to race conditions. (#5803)
+
+## 0.37.0
+
+### Implementation Changes
+
+
+* Make Publisher batch-related interfaces private (#5784)
+
+## 0.36.0
+
+### Implementation Changes
+
+
+* Pubsub: Make ‘Message.publish_time’ return datetime (#5633)
+
+
+* Ensure SPM methods check that ‘self._consumer’ is not None before use. (#5758)
+
+### New Features
+
+
+* PubSub: add geo-fencing support (#5769)
+
+
+* Add ‘Message.ack_id’ property. (#5693)
+
+## 0.35.4
+
+### Implementation Changes
+
+
+* Recover streams during the gRPC error callback. (#5446)
+
+
+* Use operational lock when checking for activity on streams. (#5445)
+
+## 0.35.3
+
+### Implementation Changes
+
+
+* Add additional error handling to unary RPCs (#5438)
+
+## 0.35.2
+
+### Implementation Changes
+
+
+* Add heartbeating to the streaming pull manager (#5413)
+
+
+* Fix retrying of bidirectional RPCs and closing the streaming pull manager (#5412)
+
+## 0.35.1
+
+### Implementation Changes
+
+
+* Catch errors when re-retying send() or recv() in addition to open() (#5402)
+
+## 0.35.0
+
+### Implementation Changes
+
+
+* Send requests during streaming pull over a separate unary RPC (#5377)
+
+
+* Initialize references to helper threads before starting them (#5374)
+
+
+* Make leaser exit more quickly (#5373)
+
+
+* Make re-open failures bubble to callbacks (#5372)
+
+
+* Avoid overwriting ‘**module**’ of messages from shared modules. (#5364)
+
+
+* Normalize overflow handling for max count and bytes (#5343)
+
+### New Features
+
+
+* Restore the synchronous pull method (#5379)
+
+
+* Promote subscribe_experimental() to subscribe(), remove old subscriber implementation. (#5274)
+
+
+* Wire up scheduler argument for subscribe() (#5279)
+
+### Documentation
+
+
+* Add link to streaming pull behavior documentation (#5378)
+
+
+* Fix example in subscribe’s documentation (#5375)
+
+### Internal / Testing Changes
+
+
+* Add Test runs for Python 3.7 and remove 3.4 (#5295)
+
+
+* Modify system tests to use prerelease versions of grpcio (#5304)
+
+## 0.34.0
+
+### Implementation Changes
+
+
+* Lower the flow control defaults. (#5248)
+
+### New Features
+
+
+* A new implementation of the subscriber has been added. This is available as `SubscriberClient.subscribe_experimental`. In the next release, this will be replace the current `subscribe` method. If you use this, please report your findings to us on GitHub. (#5189, #5201, #5210, #5229, #5230, #5237, #5256)
+
+### Dependencies
+
+
+* Remove psutil dependency. (#5248)
+
+## 0.33.1
+
+### Implementation changes
+
+
+* Surface publish RPC errors back to the publish futures (#5124)
+
+
+* Make the pausable response iterator aware of the RPC state to prevent deadlock (#5108)
+
+
+* Properly handle graceful stop in request generator (#5097)
+
+## 0.33.0
+
+### Implementation changes
+
+
+* Drop leased messages after flow_control.max_lease_duration has passed. (#5020)
+
+
+* Fix mantain leases to not modack messages it just dropped (#5045)
+
+
+* Avoid race condition in maintain_leases by copying leased_messages (#5035)
+
+
+* Retry subscription stream on InternalServerError, Unknown, and GatewayTimeout (#5021)
+
+
+* Use the rpc’s status to determine when to exit the request generator thread (#5054)
+
+
+* Fix missing iter on request stream (#5078)
+
+
+* Nack messages when the subscriber callback errors (#5019)
+
+### Testing
+
+
+* pubsub nox.py cleanup (#5056)
+
+
+* Fix test that checks for retryable exceptions (#5034)
+
+## 0.32.1
+
+### Dependencies
+
+
+* Update dependency range for api-core to include v1.0.0 releases (#4944)
+
+### Testing and internal changes
+
+
+* Install local dependencies when running lint (#4936)
+
+
+* Re-enable lint for tests, remove usage of pylint (#4921)
+
+## 0.32.0
+
+### Implementation changes
+
+
+* Added support for streaming pull receipts. (#4878)
+
+## 0.31.0
+
+### New features
+
+
+* Added the ability for subscriber to batch requests. (#4895)
+
+
+* Added pending request backpressure for subscriber. (#4892)
+
+### Implementation changes
+
+
+* Raise `ValueError` when a message is too large for a batch. (#4872)
+
+
+* Updated the default batch size to 10 MB. (#4857)
+
+
+* Allow a custom `Event` type in Pub / Sub futures. (#4643)
+
+### Documentation
+
+
+* Clarify that `modify_ack_deadline` resets the deadline. (#4822)
+
+### Testing
+
+
+* Fix unit test for default `max_bytes` value. (#4860)
+
+## 0.30.1
+
+### Notable Implementation Changes
+
+
+* Moving lock factory used in publisher client to the Batch
+implementation (#4628).
+
+
+* Use a UUID (rather than a sentinel object) on `Future` (#4634).
+
+
+* Apply scopes to explicitly provided credentials if needed (#4594).
+Fixes #4479. This feature comes as part of `google-api-core==0.1.3`.
+
+### Dependencies
+
+
+* Upgrading to `google-api-core==0.1.3` which depends on the latest
+`grpcio==1.8.2` (#4642). This fixes #4600. For details, see related
+gRPC [bug](https://github.com/grpc/grpc/issues/9688) and
+[fix](https://github.com/grpc/grpc/pull/13665).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.30.1/
+
+## 0.30.0
+
+### Notable Implementation Changes
+
+
+* Dropping redundant `Policy._paused` data member (#4568).
+
+
+* Removing redundant “active” check in policy (#4603).
+
+
+* Adding a `Consumer.active` property (#4604).
+
+
+* Making it impossible to call `Policy.open()` on an already opened
+policy (#4606).
+
+
+* **Bug fix** (#4575): Fix bug with async publish for batches. There
+were two related bugs. The first: if a batch exceeds the `max_messages`
+from the batch settings, then the `commit()` will fail. The second:
+when a “monitor” worker calls `commit()` after `max_latency` seconds,
+a failure can occur if a new message is added to the batch **during**
+the commit. To fix, the following changes were implemented:
+
+
+ * Adding a “STARTING” status for `Batch.commit()` (#4614). This
+fixes the issue when the batch exceeds `max_messages`.
+
+
+ * Adding extra check in `Batch.will_accept` for the number of
+messages (#4612).
+
+
+ * Moving `will_accept()` check out of `PublisherClient.batch()`
+factory (#4613).
+
+
+ * Checking `Batch.will_accept` in thread-safe way (#4616).
+
+
+* **Breaking API change**: As part of #4613, changing `PublisherClient.batch()`
+to no longer accept a `message` (since the `will_accept` check needs to
+happen in a more concurrency friendly way). In addition, changing the
+`create` argument so that it means “create even if batch already exists”
+rather than “create if missing”.
+
+### Documentation
+
+
+* Add more explicit documentation for `Message.attributes` (#4601).
+
+
+* Make `Message.__repr__` a bit prettier / more useful (#4602).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.30.0/
+
+## 0.29.4
+
+### Notable Implementation Changes
+
+
+* **Bug fix**: Restore previous behavior of the subscription lease
+maintenance worker. This was accidentally “stopped” in `0.29.3`
+due to a change in implementation that went from an `active`
+boolean to an “inactive” / `stopped` boolean, so `True` became
+`False` and vice-versa (#4564).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.4/
+
+## 0.29.3
+
+### Notable Implementation Changes
+
+
+* In subscription consumer thread: Making sure the request generator
+attached to an inactive bidirectional streaming pull is stopped before
+spawning a new request generator. This way we have a (fairly strong)
+guarantee that requests in the queue don’t get sent into an inactive
+stream (#4503, #4554).
+
+
+* Adding `pause` / `resume` to subscription consumer thread and using these
+methods during flow control. The previous implementation tried to close the
+subscription (which involved 3 worker threads and 10 executors in a thread
+pool) and then re-open a new subscription. But, this was not entirely
+possible to shut down correctly from **within** one of the worker threads.
+Instead, we only pause the worker (of the 3) that is pulling new responses
+from the bidirectional streaming pull (#4558).
+
+
+* **Bug fix** (#4516): Using `max` where `min` was used by mistake to
+ensure the number of bytes tracked for subscription flow control
+remained non-negative (#4514).
+
+
+* Raising `TypeError` if `SubscriberClient.subscribe` receives a
+non-callable callback (#4497).
+
+
+* Shutting down thread pool executor when closing a subscriber
+policy (#4522).
+
+
+* Renaming `Policy.on_callback_request` to `Policy.dispatch_callback`
+and making the behavior much less dynamic (#4511).
+
+
+* Make sure subscription consumer thread doesn’t try to join itself
+when exiting in error (#4540).
+
+### Dependencies
+
+
+* Upgrading `google-api-core` dependency to latest revision (`0.1.2`)
+since we rely on the latest version of the `concurrent.futures` backport
+to provide the `thread_name_prefix` argument for thread pool
+executor (#4521, #4559).
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.3/
+
+## 0.29.2
+
+### Notable Implementation Changes
+
+
+* **Bug fix** (#4463): Making a subscription consumer actually stop
+running after encountering an exception (#4472, #4498). This bug
+is the **only** reason for the `0.29.2` release.
+
+
+* Thread Changes
+
+
+ * Added names to all threads created directly by Pub / Sub (#4474,
+#4476, #4480). Also removing spaces and colons from thread
+names (#4476).
+
+
+* Logging changes
+
+
+ * Adding debug logs when lease management exits (#4484)
+
+
+ * Adding debug logs when `QueueCallbackThread` exits (#4494).
+Instances handle the processing of messages in a
+subscription (e.g. to `ack`).
+
+
+ * Using a named logger in `publisher.batch.thread` (#4473)
+
+
+ * Adding newlines before logging protobuf payloads (#4471)
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.2/
+
+## 0.29.1
+
+### Notable Implementation Changes
+
+
+* **Bug fix** (#4234): Adding retries for connection `UNAVAILABLE`. This
+bug made the Pub / Sub client mostly unusable for subscribers to topics
+that don’t have a steady stream of messages. After ~2 minutes of inactivity,
+the gRPC connection would timeout and raise `UNAVAILABLE` locally, i.e. not
+due to a response from the backend. (#4444)
+
+
+* Updating autogenerated packages (#4438)
+
+### Documentation
+
+
+* Fixing broken examples in quick start (#4398)
+
+
+* Fixing broken example in README (#4402, h/t to @mehmetboraezer)
+
+
+* Updating old/dead link to usage doc in README (#4406, h/t to @mehmetboraezer)
+
+### Dependencies
+
+
+* Dropping dependency on `google-cloud-core` in exchange for
+`google-api-core` (#4438)
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.1/
+
+## 0.29.0
+
+### Notable Implementation Changes
+
+
+* Honor `max_messages` always (#4262)
+
+
+* Add futures for subscriptions (#4265)
+
+
+* Set gRPC message options and keepalive (#4269)
+
+### Documentation
+
+
+* Added link to “Python Development Environment Setup Guide” in
+project README (#4187, h/t to @michaelawyu)
+
+### Dependencies
+
+
+* Upgrading to `google-cloud-core >= 0.28.0` and adding dependency
+on `google-api-core` (#4221, #4280)
+
+
+* Deferring to `google-api-core` for `grpcio` and
+`googleapis-common-protos` dependencies (#4096, #4098)
+
+PyPI: https://pypi.org/project/google-cloud-pubsub/0.29.0/
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.client.Client.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.client.Client.yml
new file mode 100644
index 000000000000..8266bc6836fb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.client.Client.yml
@@ -0,0 +1,1662 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.publisher.client.Client
+ - google.cloud.pubsub_v1.publisher.client.Client.__exit__
+ - google.cloud.pubsub_v1.publisher.client.Client.api
+ - google.cloud.pubsub_v1.publisher.client.Client.common_billing_account_path
+ - google.cloud.pubsub_v1.publisher.client.Client.common_folder_path
+ - google.cloud.pubsub_v1.publisher.client.Client.common_location_path
+ - google.cloud.pubsub_v1.publisher.client.Client.common_organization_path
+ - google.cloud.pubsub_v1.publisher.client.Client.common_project_path
+ - google.cloud.pubsub_v1.publisher.client.Client.create_topic
+ - google.cloud.pubsub_v1.publisher.client.Client.delete_topic
+ - google.cloud.pubsub_v1.publisher.client.Client.detach_subscription
+ - google.cloud.pubsub_v1.publisher.client.Client.ensure_cleanup_and_commit_timer_runs
+ - google.cloud.pubsub_v1.publisher.client.Client.from_service_account_file
+ - google.cloud.pubsub_v1.publisher.client.Client.from_service_account_info
+ - google.cloud.pubsub_v1.publisher.client.Client.from_service_account_json
+ - google.cloud.pubsub_v1.publisher.client.Client.get_iam_policy
+ - google.cloud.pubsub_v1.publisher.client.Client.get_mtls_endpoint_and_cert_source
+ - google.cloud.pubsub_v1.publisher.client.Client.get_topic
+ - google.cloud.pubsub_v1.publisher.client.Client.list_topic_snapshots
+ - google.cloud.pubsub_v1.publisher.client.Client.list_topic_subscriptions
+ - google.cloud.pubsub_v1.publisher.client.Client.list_topics
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_common_billing_account_path
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_common_folder_path
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_common_location_path
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_common_organization_path
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_common_project_path
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_schema_path
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_subscription_path
+ - google.cloud.pubsub_v1.publisher.client.Client.parse_topic_path
+ - google.cloud.pubsub_v1.publisher.client.Client.publish
+ - google.cloud.pubsub_v1.publisher.client.Client.resume_publish
+ - google.cloud.pubsub_v1.publisher.client.Client.schema_path
+ - google.cloud.pubsub_v1.publisher.client.Client.set_iam_policy
+ - google.cloud.pubsub_v1.publisher.client.Client.stop
+ - google.cloud.pubsub_v1.publisher.client.Client.subscription_path
+ - google.cloud.pubsub_v1.publisher.client.Client.target
+ - google.cloud.pubsub_v1.publisher.client.Client.test_iam_permissions
+ - google.cloud.pubsub_v1.publisher.client.Client.topic_path
+ - google.cloud.pubsub_v1.publisher.client.Client.transport
+ - google.cloud.pubsub_v1.publisher.client.Client.update_topic
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: Client
+ source:
+ id: Client
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 65
+ summary: 'A publisher client for Google Cloud Pub/Sub.
+
+
+ This creates an object that is capable of publishing messages.
+
+ Generally, you can instantiate this client with no arguments, and you
+
+ get sensible defaults.
+
+ '
+ syntax:
+ content: "Client(\n batch_settings: typing.Union[\n google.cloud.pubsub_v1.types.BatchSettings,\
+ \ typing.Sequence\n ] = (),\n publisher_options: typing.Union[\n \
+ \ google.cloud.pubsub_v1.types.PublisherOptions, typing.Sequence\n ] =\
+ \ (),\n **kwargs: typing.Any\n)"
+ parameters:
+ - description: The settings for batch publishing.
+ id: batch_settings
+ var_type: typing.Union[google.cloud.pubsub_v1.types.BatchSettings ,
+ typing.Sequence]
+ - defaultValue: ()
+ description: The options for the publisher client. Note that enabling message
+ ordering will override the publish retry timeout to be infinite.
+ id: publisher_options
+ var_type: typing.Union[google.cloud.pubsub_v1.types.PublisherOptions ,
+ typing.Sequence]
+ type: class
+ uid: google.cloud.pubsub_v1.publisher.client.Client
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: Client
+ source:
+ id: Client
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 65
+ summary: 'Instantiates the publisher client.
+
+ '
+ syntax:
+ content: "Client(\n batch_settings: typing.Union[\n google.cloud.pubsub_v1.types.BatchSettings,\
+ \ typing.Sequence\n ] = (),\n publisher_options: typing.Union[\n \
+ \ google.cloud.pubsub_v1.types.PublisherOptions, typing.Sequence\n ] =\
+ \ (),\n **kwargs: typing.Any\n)"
+ exceptions:
+ - description: If mutual TLS transport creation failed for any reason.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - description: The authorization credentials to attach to requests. These credentials
+ identify the application to the service; if none are specified, the client
+ will attempt to ascertain the credentials from the environment.
+ id: credentials
+ var_type: Optional[google.auth.credentials.Credentials]
+ - description: The transport to use. If set to None, a transport is chosen automatically.
+ id: transport
+ var_type: Union[str, PublisherTransport]
+ - description: 'Custom options for the client. It won''t take effect if a transport
+ instance is provided. (1) The api_endpoint property can be used
+ to override the default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint: "always" (always
+ use the default mTLS endpoint), "never" (always use the default regular endpoint)
+ and "auto" (auto switch to the default mTLS endpoint if client certificate
+ is present, this is the default value). However, the api_endpoint
+ property takes precedence if provided. (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ environment variable is "true", then the client_cert_source property
+ can be used to provide client certificate for mutual TLS transport. If not
+ provided, the default SSL client certificate will be used if present. If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ is "false" or not set, no client certificate will be used.'
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ - description: The client info used to send a user-agent string along with API
+ requests. If None, then default info will be used. Generally,
+ you only need to set this if you're developing your own client library.
+ id: client_info
+ var_type: google.api_core.gapic_v1.client_info.ClientInfo
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.__exit__
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: __exit__
+ source:
+ id: __exit__
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1430
+ summary: 'Releases underlying transport''s resources.
+
+
+
+
+ Warning:
+
+ ONLY use as a context manager if the transport is NOT shared
+
+ with other clients! Exiting the with block will CLOSE the transport
+
+ and may cause errors in other clients!
+
+ '
+ syntax:
+ content: __exit__(type, value, traceback)
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.__exit__
+- &id001
+ attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.api
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: api
+ source:
+ id: api
+ path: null
+ startLine: null
+ summary: "The underlying gapic API client.\n\n.. versionchanged:: 2.10.0\n Instead\
+ \ of a GAPIC `PublisherClient` client instance, this property is a\n proxy\
+ \ object to it with the same interface.\n\n\ndeprecated: \n\
+ Use the GAPIC methods and properties on the client instance directly\ninstead\
+ \ of through the `api` attribute.\n "
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.publisher.client.Client.api
+- *id001
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: common_billing_account_path
+ source:
+ id: common_billing_account_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 236
+ summary: 'Returns a fully-qualified billing_account string.
+
+
+ '
+ syntax:
+ content: 'common_billing_account_path(billing_account: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_billing_account_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.common_folder_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: common_folder_path
+ source:
+ id: common_folder_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 251
+ summary: 'Returns a fully-qualified folder string.
+
+
+ '
+ syntax:
+ content: 'common_folder_path(folder: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_folder_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.common_location_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: common_location_path
+ source:
+ id: common_location_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 296
+ summary: 'Returns a fully-qualified location string.
+
+
+ '
+ syntax:
+ content: 'common_location_path(project: str, location: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_location_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.common_organization_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: common_organization_path
+ source:
+ id: common_organization_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 266
+ summary: 'Returns a fully-qualified organization string.
+
+
+ '
+ syntax:
+ content: 'common_organization_path(organization: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_organization_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.common_project_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: common_project_path
+ source:
+ id: common_project_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 281
+ summary: 'Returns a fully-qualified project string.
+
+
+ '
+ syntax:
+ content: 'common_project_path(project: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_project_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.create_topic
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: create_topic
+ source:
+ id: create_topic
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 488
+ summary: "Creates the given topic with the given name. See the [resource\nname rules]\n\
+ (https://cloud.google.com/pubsub/docs/admin#resource_names).\n\n```python\n# This\
+ \ snippet has been automatically generated and should be regarded as a\n# code\
+ \ template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_create_topic():\n # Create a client\n\
+ \ client = pubsub_v1.PublisherClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.Topic(\n name=\"name_value\",\n )\n\n #\
+ \ Make the request\n response = client.create_topic(request=request)\n\n \
+ \ # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "create_topic(\n request: typing.Union[google.cloud.pubsub_v1.types.Topic,\
+ \ dict] = None,\n *,\n name: str = None,\n retry: typing.Union[\n \
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Union[\n \
+ \ int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.cloud.pubsub_v1.types.Topic"
+ parameters:
+ - defaultValue: None
+ description: The request object. A topic resource.
+ id: request
+ var_type: Union[google.pubsub_v1.types.Topic, dict]
+ - description: Required. The name of the topic. It must have the format "projects/{project}/topics/{topic}".
+ {topic} must start with a letter, and contain only letters ([A-Za-z]),
+ numbers ([0-9]), dashes (-), underscores (`_),
+ periods (.), tildes (+)
+ or percent signs (%). It must be between 3 and 255 characters
+ in length, and it must not start with "goog". This corresponds
+ to the name field on the request instance; if request`
+ is provided, this should not be set.
+ id: name
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A topic resource.
+ var_type: google.pubsub_v1.types.Topic
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.create_topic
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.delete_topic
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: delete_topic
+ source:
+ id: delete_topic
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1243
+ summary: "Deletes the topic with the given name. Returns `NOT_FOUND` if\nthe topic\
+ \ does not exist. After a topic is deleted, a new topic\nmay be created with the\
+ \ same name; this is an entirely new topic\nwith none of the old configuration\
+ \ or subscriptions. Existing\nsubscriptions to this topic are not deleted, but\
+ \ their `topic`\nfield is set to `_deleted-topic_`.\n\n```python\n# This snippet\
+ \ has been automatically generated and should be regarded as a\n# code template\
+ \ only.\n# It will require modifications to work:\n# - It may require correct/in-range\
+ \ values for request initialization.\n# - It may require specifying regional endpoints\
+ \ when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_delete_topic():\n # Create a client\n\
+ \ client = pubsub_v1.PublisherClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.DeleteTopicRequest(\n topic=\"topic_value\",\n\
+ \ )\n\n # Make the request\n client.delete_topic(request=request)\n```\n"
+ syntax:
+ content: "delete_topic(\n request: typing.Union[google.cloud.pubsub_v1.types.DeleteTopicRequest,\
+ \ dict] = None,\n *,\n topic: str = None,\n retry: typing.Union[\n\
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Union[\n \
+ \ int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> None"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the DeleteTopic method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.DeleteTopicRequest, dict]
+ - description: Required. Name of the topic to delete. Format is projects/{project}/topics/{topic}.
+ This corresponds to the topic field on the request
+ instance; if request is provided, this should not be set.
+ id: topic
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.delete_topic
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.detach_subscription
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: detach_subscription
+ source:
+ id: detach_subscription
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1339
+ summary: "Detaches a subscription from this topic. All messages retained\nin the\
+ \ subscription are dropped. Subsequent `Pull` and\n`StreamingPull` requests will\
+ \ return FAILED_PRECONDITION. If\nthe subscription is a push subscription, pushes\
+ \ to the endpoint\nwill stop.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_detach_subscription():\n # Create\
+ \ a client\n client = pubsub_v1.PublisherClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.DetachSubscriptionRequest(\n subscription=\"\
+ subscription_value\",\n )\n\n # Make the request\n response = client.detach_subscription(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "detach_subscription(\n request: typing.Union[\n google.cloud.pubsub_v1.types.DetachSubscriptionRequest,\
+ \ dict\n ] = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Union[\n int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.cloud.pubsub_v1.types.DetachSubscriptionResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the DetachSubscription method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.DetachSubscriptionRequest, dict]
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the DetachSubscription method. Reserved for future
+ use.
+ var_type: google.pubsub_v1.types.DetachSubscriptionResponse
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.detach_subscription
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.ensure_cleanup_and_commit_timer_runs
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: ensure_cleanup_and_commit_timer_runs
+ source:
+ id: ensure_cleanup_and_commit_timer_runs
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 421
+ summary: 'Ensure a cleanup/commit timer thread is running.
+
+
+ If a cleanup/commit timer thread is already running, this does nothing.
+
+
+ '
+ syntax:
+ content: ensure_cleanup_and_commit_timer_runs() -> None
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.ensure_cleanup_and_commit_timer_runs
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_file
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: from_service_account_file
+ source:
+ id: from_service_account_file
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 161
+ summary: 'Creates an instance of this client using the provided credentials
+
+ file.
+
+ '
+ syntax:
+ content: "from_service_account_file(\n filename: str,\n batch_settings:\
+ \ typing.Union[\n google.cloud.pubsub_v1.types.BatchSettings, typing.Sequence\n\
+ \ ] = (),\n **kwargs: typing.Any\n) -> google.cloud.pubsub_v1.publisher.client.Client"
+ parameters:
+ - description: The path to the service account private key JSON file.
+ id: filename
+ var_type: str
+ - description: The settings for batch publishing.
+ id: batch_settings
+ var_type: typing.Union[google.cloud.pubsub_v1.types.BatchSettings ,
+ typing.Sequence]
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_file
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_info
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: from_service_account_info
+ source:
+ id: from_service_account_info
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 136
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ info.\n"
+ syntax:
+ content: 'from_service_account_info(info: dict, *args, **kwargs)'
+ parameters:
+ - description: The service account private key info.
+ id: info
+ var_type: dict
+ returns:
+ - description: The constructed client.
+ var_type: PublisherClient
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_info
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_json
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: from_service_account_json
+ source:
+ id: from_service_account_json
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 161
+ summary: 'Creates an instance of this client using the provided credentials
+
+ file.
+
+ '
+ syntax:
+ content: "from_service_account_json(\n filename: str,\n batch_settings:\
+ \ typing.Union[\n google.cloud.pubsub_v1.types.BatchSettings, typing.Sequence\n\
+ \ ] = (),\n **kwargs: typing.Any\n) -> google.cloud.pubsub_v1.publisher.client.Client"
+ parameters:
+ - description: The path to the service account private key JSON file.
+ id: filename
+ var_type: str
+ - description: The settings for batch publishing.
+ id: batch_settings
+ var_type: typing.Union[google.cloud.pubsub_v1.types.BatchSettings ,
+ typing.Sequence]
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_json
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.get_iam_policy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: get_iam_policy
+ source:
+ id: get_iam_policy
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1561
+ summary: 'Gets the IAM access control policy for a function.
+
+
+ Returns an empty policy if the function exists and does not have a
+
+ policy set.
+
+ '
+ syntax:
+ content: "get_iam_policy(\n request: google.iam.v1.iam_policy_pb2.GetIamPolicyRequest\
+ \ = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Union[\n int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.iam.v1.policy_pb2.Policy"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request message for GetIamPolicy
+ method.
+ id: request
+ var_type: .iam_policy_pb2.GetIamPolicyRequest
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: 'Defines an Identity and Access Management (IAM) policy. It is
+ used to specify access control policies for Cloud Platform resources. A Policy
+ is a collection of bindings. A binding binds one
+ or more members to a single role. Members can be
+ user accounts, service accounts, Google groups, and domains (such as G Suite).
+ A role is a named list of permissions (defined by IAM or configured
+ by users). A binding can optionally specify a condition,
+ which is a logic expression that further constrains the role binding based
+ on attributes about the request and/or target resource. **JSON Example** ::
+ { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members":
+ [ "user:mike@example.com", "group:admins@example.com", "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role":
+ "roles/resourcemanager.organizationViewer", "members": ["user:eve@example.com"],
+ "condition": { "title": "expirable access", "description": "Does not grant
+ access after Sep 2020", "expression": "request.time < timestamp(''2020-10-01T00:00:00.000Z'')",
+ } } ] } **YAML Example** :: bindings: - members: - user:mike@example.com -
+ group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer condition: title: expirable
+ access description: Does not grant access after Sep 2020 expression: request.time
+ < timestamp(''2020-10-01T00:00:00.000Z'') For a description of IAM and its
+ features, see the IAM developer''s guide __.'
+ var_type: .policy_pb2.Policy
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.get_iam_policy
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.get_mtls_endpoint_and_cert_source
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: get_mtls_endpoint_and_cert_source
+ source:
+ id: get_mtls_endpoint_and_cert_source
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 313
+ summary: 'Return the API endpoint and client cert source for mutual TLS.
+
+
+ The client cert source is determined in the following order:
+
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true",
+ the
+
+ client cert source is None.
+
+ (2) if `client_options.client_cert_source` is provided, use the provided one;
+ if the
+
+ default client cert source exists, use the default one; otherwise the client cert
+
+ source is None.
+
+
+ The API endpoint is determined in the following order:
+
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use
+ the
+
+ default mTLS endpoint; if the environment variabel is "never", use the default
+ API
+
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint,
+ otherwise
+
+ use the default API endpoint.
+
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ '
+ syntax:
+ content: "get_mtls_endpoint_and_cert_source(\n client_options: typing.Optional[\n\
+ \ google.api_core.client_options.ClientOptions\n ] = None,\n)"
+ exceptions:
+ - description: If any errors happen.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - defaultValue: None
+ description: Custom options for the client. Only the api_endpoint
+ and client_cert_source properties may be used in this method.
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ returns:
+ - description: returns the API endpoint and the client cert source to use.
+ var_type: Tuple[str, Callable[[], Tuple[bytes, bytes]]]
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.get_mtls_endpoint_and_cert_source
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.get_topic
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: get_topic
+ source:
+ id: get_topic
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 791
+ summary: "Gets the configuration of a topic.\n\n```python\n# This snippet has been\
+ \ automatically generated and should be regarded as a\n# code template only.\n\
+ # It will require modifications to work:\n# - It may require correct/in-range\
+ \ values for request initialization.\n# - It may require specifying regional endpoints\
+ \ when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_get_topic():\n # Create a client\n\
+ \ client = pubsub_v1.PublisherClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.GetTopicRequest(\n topic=\"topic_value\",\n \
+ \ )\n\n # Make the request\n response = client.get_topic(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "get_topic(\n request: typing.Union[google.cloud.pubsub_v1.types.GetTopicRequest,\
+ \ dict] = None,\n *,\n topic: str = None,\n retry: typing.Union[\n\
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Union[\n \
+ \ int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.cloud.pubsub_v1.types.Topic"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the GetTopic method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.GetTopicRequest, dict]
+ - description: Required. The name of the topic to get. Format is projects/{project}/topics/{topic}.
+ This corresponds to the topic field on the request
+ instance; if request is provided, this should not be set.
+ id: topic
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A topic resource.
+ var_type: google.pubsub_v1.types.Topic
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.get_topic
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.list_topic_snapshots
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: list_topic_snapshots
+ source:
+ id: list_topic_snapshots
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1122
+ summary: "Lists the names of the snapshots on this topic. Snapshots are\nused in\n\
+ `Seek `__\noperations, which\
+ \ allow you to manage message acknowledgments in\nbulk. That is, you can set the\
+ \ acknowledgment state of messages\nin an existing subscription to the state captured\
+ \ by a snapshot.\n\n```python\n# This snippet has been automatically generated\
+ \ and should be regarded as a\n# code template only.\n# It will require modifications\
+ \ to work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_list_topic_snapshots():\n # Create\
+ \ a client\n client = pubsub_v1.PublisherClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.ListTopicSnapshotsRequest(\n topic=\"\
+ topic_value\",\n )\n\n # Make the request\n page_result = client.list_topic_snapshots(request=request)\n\
+ \n # Handle the response\n for response in page_result:\n print(response)\n\
+ ```\n"
+ syntax:
+ content: "list_topic_snapshots(\n request: typing.Union[\n google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest,\
+ \ dict\n ] = None,\n *,\n topic: str = None,\n retry: typing.Union[\n\
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Union[\n \
+ \ int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the ListTopicSnapshots
+ method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.ListTopicSnapshotsRequest, dict]
+ - description: Required. The name of the topic that snapshots are attached to.
+ Format is projects/{project}/topics/{topic}. This corresponds
+ to the topic field on the request instance; if request
+ is provided, this should not be set.
+ id: topic
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the ListTopicSnapshots method. Iterating over this
+ object will yield results and resolve additional pages automatically.
+ var_type: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.list_topic_snapshots
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.list_topic_subscriptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: list_topic_subscriptions
+ source:
+ id: list_topic_subscriptions
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1005
+ summary: "Lists the names of the attached subscriptions on this\ntopic.\n\n```python\n\
+ # This snippet has been automatically generated and should be regarded as a\n\
+ # code template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_list_topic_subscriptions():\n #\
+ \ Create a client\n client = pubsub_v1.PublisherClient()\n\n # Initialize\
+ \ request argument(s)\n request = pubsub_v1.ListTopicSubscriptionsRequest(\n\
+ \ topic=\"topic_value\",\n )\n\n # Make the request\n page_result\
+ \ = client.list_topic_subscriptions(request=request)\n\n # Handle the response\n\
+ \ for response in page_result:\n print(response)\n```\n"
+ syntax:
+ content: "list_topic_subscriptions(\n request: typing.Union[\n google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest,\
+ \ dict\n ] = None,\n *,\n topic: str = None,\n retry: typing.Union[\n\
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Union[\n \
+ \ int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the ListTopicSubscriptions
+ method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.ListTopicSubscriptionsRequest, dict]
+ - description: Required. The name of the topic that subscriptions are attached
+ to. Format is projects/{project}/topics/{topic}. This corresponds
+ to the topic field on the request instance; if request
+ is provided, this should not be set.
+ id: topic
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the ListTopicSubscriptions method. Iterating over
+ this object will yield results and resolve additional pages automatically.
+ var_type: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.list_topic_subscriptions
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.list_topics
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: list_topics
+ source:
+ id: list_topics
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 891
+ summary: "Lists matching topics.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_list_topics():\n # Create a client\n\
+ \ client = pubsub_v1.PublisherClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.ListTopicsRequest(\n project=\"project_value\"\
+ ,\n )\n\n # Make the request\n page_result = client.list_topics(request=request)\n\
+ \n # Handle the response\n for response in page_result:\n print(response)\n\
+ ```\n"
+ syntax:
+ content: "list_topics(\n request: typing.Union[google.cloud.pubsub_v1.types.ListTopicsRequest,\
+ \ dict] = None,\n *,\n project: str = None,\n retry: typing.Union[\n\
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Union[\n \
+ \ int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.pubsub_v1.services.publisher.pagers.ListTopicsPager"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the ListTopics method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.ListTopicsRequest, dict]
+ - description: Required. The name of the project in which to list topics. Format
+ is projects/{project-id}. This corresponds to the project
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: project
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the ListTopics method. Iterating over this object
+ will yield results and resolve additional pages automatically.
+ var_type: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.list_topics
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_common_billing_account_path
+ source:
+ id: parse_common_billing_account_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 245
+ summary: 'Parse a billing_account path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_billing_account_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_billing_account_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_folder_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_common_folder_path
+ source:
+ id: parse_common_folder_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 260
+ summary: 'Parse a folder path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_folder_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_folder_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_location_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_common_location_path
+ source:
+ id: parse_common_location_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 307
+ summary: 'Parse a location path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_location_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_location_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_organization_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_common_organization_path
+ source:
+ id: parse_common_organization_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 275
+ summary: 'Parse a organization path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_organization_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_organization_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_project_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_common_project_path
+ source:
+ id: parse_common_project_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 290
+ summary: 'Parse a project path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_project_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_project_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_schema_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_schema_path
+ source:
+ id: parse_schema_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 194
+ summary: 'Parses a schema path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_schema_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_schema_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_subscription_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_subscription_path
+ source:
+ id: parse_subscription_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 211
+ summary: 'Parses a subscription path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_subscription_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_subscription_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_topic_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: parse_topic_path
+ source:
+ id: parse_topic_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 230
+ summary: 'Parses a topic path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_topic_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_topic_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.publish
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: publish
+ source:
+ id: publish
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 274
+ summary: "Publish a single message.\n\n\nNote: \nMessages\
+ \ in Pub/Sub are blobs of bytes. They are *binary* data,\nnot text. You must send\
+ \ data as a bytestring\n(`bytes` in Python 3; `str` in Python 2), and this library\n\
+ will raise an exception if you send a text string.\n \n The reason that\
+ \ this is so important (and why we do not try to\n coerce for you) is because\
+ \ Pub/Sub is also platform independent\n and there is no way to know how to\
+ \ decode messages properly on\n the other side; therefore, encoding and decoding\
+ \ is a required\n exercise for the developer.\n\nAdd the given message to this\
+ \ object; this will cause it to be\npublished once the batch either has enough\
+ \ messages or a sufficient\nperiod of time has elapsed.\nThis method may block\
+ \ if LimitExceededBehavior.BLOCK is used in the\nflow control settings.\n\n..\
+ \ rubric:: Example\n\n>>> from google.cloud import pubsub_v1\n>>> client = pubsub_v1.PublisherClient()\n\
+ >>> topic = client.topic_path('[PROJECT]', '[TOPIC]')\n>>> data = b'The rain in\
+ \ Wales falls mainly on the snails.'\n>>> response = client.publish(topic, data,\
+ \ username='guido')\n"
+ syntax:
+ content: "publish(\n topic: str,\n data: bytes,\n ordering_key: str =\
+ \ \"\",\n retry: OptionalRetry = _MethodDefault._DEFAULT_VALUE,\n timeout:\
+ \ types.OptionalTimeout = _MethodDefault._DEFAULT_VALUE,\n **attrs: typing.Union[bytes,\
+ \ str]\n) -> pubsub_v1.publisher.futures.Future"
+ exceptions:
+ - description: If called after publisher has been stopped by a stop()
+ method call.
+ var_type: RuntimeError
+ - description: If publishing the message would exceed the max size
+ limit on the backend.
+ var_type: pubsub_v1.publisher.exceptions.MessageTooLargeError
+ parameters:
+ - description: The topic to publish messages to.
+ id: topic
+ var_type: str
+ - defaultValue: ''
+ description: A bytestring representing the message body. This must be a bytestring.
+ id: data
+ var_type: bytes
+ - defaultValue: _MethodDefault._DEFAULT_VALUE
+ description: A string that identifies related messages for which publish order
+ should be respected. Message ordering must be enabled for this client to use
+ this feature.
+ id: ordering_key
+ var_type: str
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.publish
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.resume_publish
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: resume_publish
+ source:
+ id: resume_publish
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 234
+ summary: 'Resume publish on an ordering key that has had unrecoverable errors.
+
+ '
+ syntax:
+ content: 'resume_publish(topic: str, ordering_key: str) -> None'
+ exceptions:
+ - description: If called after publisher has been stopped by a stop()
+ method call.
+ var_type: RuntimeError
+ - description: If the topic/ordering key combination has not been seen before
+ by this client.
+ var_type: ValueError
+ parameters:
+ - description: The topic to publish messages to.
+ id: topic
+ var_type: str
+ - description: A string that identifies related messages for which publish order
+ should be respected.
+ id: ordering_key
+ var_type: str
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.resume_publish
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.schema_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: schema_path
+ source:
+ id: schema_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 183
+ summary: 'Returns a fully-qualified schema string.
+
+
+ '
+ syntax:
+ content: 'schema_path(project: str, schema: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.schema_path
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.set_iam_policy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: set_iam_policy
+ source:
+ id: set_iam_policy
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1440
+ summary: 'Sets the IAM access control policy on the specified function.
+
+
+ Replaces any existing policy.
+
+ '
+ syntax:
+ content: "set_iam_policy(\n request: google.iam.v1.iam_policy_pb2.SetIamPolicyRequest\
+ \ = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Union[\n int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.iam.v1.policy_pb2.Policy"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request message for SetIamPolicy
+ method.
+ id: request
+ var_type: .iam_policy_pb2.SetIamPolicyRequest
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: 'Defines an Identity and Access Management (IAM) policy. It is
+ used to specify access control policies for Cloud Platform resources. A Policy
+ is a collection of bindings. A binding binds one
+ or more members to a single role. Members can be
+ user accounts, service accounts, Google groups, and domains (such as G Suite).
+ A role is a named list of permissions (defined by IAM or configured
+ by users). A binding can optionally specify a condition,
+ which is a logic expression that further constrains the role binding based
+ on attributes about the request and/or target resource. **JSON Example** ::
+ { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members":
+ [ "user:mike@example.com", "group:admins@example.com", "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role":
+ "roles/resourcemanager.organizationViewer", "members": ["user:eve@example.com"],
+ "condition": { "title": "expirable access", "description": "Does not grant
+ access after Sep 2020", "expression": "request.time < timestamp(''2020-10-01T00:00:00.000Z'')",
+ } } ] } **YAML Example** :: bindings: - members: - user:mike@example.com -
+ group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer condition: title: expirable
+ access description: Does not grant access after Sep 2020 expression: request.time
+ < timestamp(''2020-10-01T00:00:00.000Z'') For a description of IAM and its
+ features, see the IAM developer''s guide __.'
+ var_type: .policy_pb2.Policy
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.set_iam_policy
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.stop
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: stop
+ source:
+ id: stop
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 475
+ summary: 'Immediately publish all outstanding messages.
+
+
+ Asynchronously sends all outstanding messages and
+
+ prevents future calls to `publish()`. Method should
+
+ be invoked prior to deleting this `Client()` object
+
+ in order to ensure that no pending messages are lost.
+
+
+
+
+ Note:
+
+ This method is non-blocking. Use `Future()` objects
+
+ returned by `publish()` to make sure all publish
+
+ requests completed, either in success or error.
+
+ '
+ syntax:
+ content: stop() -> None
+ exceptions:
+ - description: If called after publisher has been stopped by a stop()
+ method call.
+ var_type: RuntimeError
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.stop
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.subscription_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: subscription_path
+ source:
+ id: subscription_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 200
+ summary: 'Returns a fully-qualified subscription string.
+
+
+ '
+ syntax:
+ content: 'subscription_path(project: str, subscription: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.subscription_path
+- &id002
+ attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.target
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: target
+ source:
+ id: target
+ path: null
+ startLine: null
+ summary: 'Return the target (where the API is).
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.publisher.client.Client.target
+- *id002
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.test_iam_permissions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: test_iam_permissions
+ source:
+ id: test_iam_permissions
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 1683
+ summary: "Tests the specified IAM permissions against the IAM access control\n \
+ \ policy for a function.\n\nIf the function does not exist, this will return\
+ \ an empty set\nof permissions, not a NOT_FOUND error.\n"
+ syntax:
+ content: "test_iam_permissions(\n request: google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest\
+ \ = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Union[\n int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request message for TestIamPermissions
+ method.
+ id: request
+ var_type: .iam_policy_pb2.TestIamPermissionsRequest
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response message for TestIamPermissions method.
+ var_type: .iam_policy_pb2.TestIamPermissionsResponse
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.test_iam_permissions
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.topic_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: topic_path
+ source:
+ id: topic_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 219
+ summary: 'Returns a fully-qualified topic string.
+
+
+ '
+ syntax:
+ content: 'topic_path(project: str, topic: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.topic_path
+- &id003
+ attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.transport
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: transport
+ source:
+ id: transport
+ path: null
+ startLine: null
+ summary: 'Returns the transport used by the client instance.
+
+ '
+ syntax:
+ returns:
+ - description: The transport used by the client instance.
+ var_type: PublisherTransport
+ type: property
+ uid: google.cloud.pubsub_v1.publisher.client.Client.transport
+- *id003
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client.Client.update_topic
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: update_topic
+ source:
+ id: update_topic
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/client.py
+ startLine: 596
+ summary: "Updates an existing topic. Note that certain\nproperties of a topic are\
+ \ not modifiable.\n\n```python\n# This snippet has been automatically generated\
+ \ and should be regarded as a\n# code template only.\n# It will require modifications\
+ \ to work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_update_topic():\n # Create a client\n\
+ \ client = pubsub_v1.PublisherClient()\n\n # Initialize request argument(s)\n\
+ \ topic = pubsub_v1.Topic()\n topic.name = \"name_value\"\n\n request\
+ \ = pubsub_v1.UpdateTopicRequest(\n topic=topic,\n )\n\n # Make the\
+ \ request\n response = client.update_topic(request=request)\n\n # Handle\
+ \ the response\n print(response)\n```\n"
+ syntax:
+ content: "update_topic(\n request: typing.Union[google.cloud.pubsub_v1.types.UpdateTopicRequest,\
+ \ dict] = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Union[\n int,\n float,\n google.api_core.timeout.ConstantTimeout,\n\
+ \ google.api_core.timeout.ExponentialTimeout,\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) -> google.cloud.pubsub_v1.types.Topic"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the UpdateTopic method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.UpdateTopicRequest, dict]
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: TimeoutType
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A topic resource.
+ var_type: google.pubsub_v1.types.Topic
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.client.Client.update_topic
+references:
+- fullName: google.cloud.pubsub_v1.publisher.client.Client
+ isExternal: false
+ name: Client
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.__exit__
+ isExternal: false
+ name: __exit__
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.__exit__
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.api
+ isExternal: false
+ name: api
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.api
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.common_billing_account_path
+ isExternal: false
+ name: common_billing_account_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_billing_account_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.common_folder_path
+ isExternal: false
+ name: common_folder_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_folder_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.common_location_path
+ isExternal: false
+ name: common_location_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_location_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.common_organization_path
+ isExternal: false
+ name: common_organization_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_organization_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.common_project_path
+ isExternal: false
+ name: common_project_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.common_project_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.create_topic
+ isExternal: false
+ name: create_topic
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.create_topic
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.delete_topic
+ isExternal: false
+ name: delete_topic
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.delete_topic
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.detach_subscription
+ isExternal: false
+ name: detach_subscription
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.detach_subscription
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.ensure_cleanup_and_commit_timer_runs
+ isExternal: false
+ name: ensure_cleanup_and_commit_timer_runs
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.ensure_cleanup_and_commit_timer_runs
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_file
+ isExternal: false
+ name: from_service_account_file
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_file
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_info
+ isExternal: false
+ name: from_service_account_info
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_info
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_json
+ isExternal: false
+ name: from_service_account_json
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.from_service_account_json
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.get_iam_policy
+ isExternal: false
+ name: get_iam_policy
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.get_iam_policy
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.get_mtls_endpoint_and_cert_source
+ isExternal: false
+ name: get_mtls_endpoint_and_cert_source
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.get_mtls_endpoint_and_cert_source
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.get_topic
+ isExternal: false
+ name: get_topic
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.get_topic
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.list_topic_snapshots
+ isExternal: false
+ name: list_topic_snapshots
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.list_topic_snapshots
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.list_topic_subscriptions
+ isExternal: false
+ name: list_topic_subscriptions
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.list_topic_subscriptions
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.list_topics
+ isExternal: false
+ name: list_topics
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.list_topics
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_billing_account_path
+ isExternal: false
+ name: parse_common_billing_account_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_billing_account_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_folder_path
+ isExternal: false
+ name: parse_common_folder_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_folder_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_location_path
+ isExternal: false
+ name: parse_common_location_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_location_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_organization_path
+ isExternal: false
+ name: parse_common_organization_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_organization_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_common_project_path
+ isExternal: false
+ name: parse_common_project_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_common_project_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_schema_path
+ isExternal: false
+ name: parse_schema_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_schema_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_subscription_path
+ isExternal: false
+ name: parse_subscription_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_subscription_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.parse_topic_path
+ isExternal: false
+ name: parse_topic_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.parse_topic_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.publish
+ isExternal: false
+ name: publish
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.publish
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.resume_publish
+ isExternal: false
+ name: resume_publish
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.resume_publish
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.schema_path
+ isExternal: false
+ name: schema_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.schema_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.set_iam_policy
+ isExternal: false
+ name: set_iam_policy
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.set_iam_policy
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.stop
+ isExternal: false
+ name: stop
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.stop
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.subscription_path
+ isExternal: false
+ name: subscription_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.subscription_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.target
+ isExternal: false
+ name: target
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.target
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.test_iam_permissions
+ isExternal: false
+ name: test_iam_permissions
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.test_iam_permissions
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.topic_path
+ isExternal: false
+ name: topic_path
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.topic_path
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.transport
+ isExternal: false
+ name: transport
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.transport
+- fullName: google.cloud.pubsub_v1.publisher.client.Client.update_topic
+ isExternal: false
+ name: update_topic
+ parent: google.cloud.pubsub_v1.publisher.client.Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client.update_topic
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.client.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.client.yml
new file mode 100644
index 000000000000..386cf39c0d47
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.client.yml
@@ -0,0 +1,24 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.publisher.client.Client
+ fullName: google.cloud.pubsub_v1.publisher.client
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.client
+ name: publisher.client
+ source:
+ id: client
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/client.py
+ startLine: 0
+ summary: API documentation for `pubsub_v1.publisher.client` module.
+ syntax: {}
+ type: module
+ uid: google.cloud.pubsub_v1.publisher.client
+references:
+- fullName: google.cloud.pubsub_v1.publisher.client.Client
+ isExternal: false
+ name: Client
+ parent: google.cloud.pubsub_v1.publisher.client
+ uid: google.cloud.pubsub_v1.publisher.client.Client
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.futures.Future.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.futures.Future.yml
new file mode 100644
index 000000000000..3c4d8039f7a4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.futures.Future.yml
@@ -0,0 +1,384 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.publisher.futures.Future
+ - google.cloud.pubsub_v1.publisher.futures.Future.add_done_callback
+ - google.cloud.pubsub_v1.publisher.futures.Future.cancel
+ - google.cloud.pubsub_v1.publisher.futures.Future.cancelled
+ - google.cloud.pubsub_v1.publisher.futures.Future.done
+ - google.cloud.pubsub_v1.publisher.futures.Future.exception
+ - google.cloud.pubsub_v1.publisher.futures.Future.result
+ - google.cloud.pubsub_v1.publisher.futures.Future.running
+ - google.cloud.pubsub_v1.publisher.futures.Future.set_exception
+ - google.cloud.pubsub_v1.publisher.futures.Future.set_result
+ - google.cloud.pubsub_v1.publisher.futures.Future.set_running_or_notify_cancel
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: Future
+ source:
+ id: Future
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
+ startLine: 26
+ summary: 'This future object is returned from asychronous Pub/Sub publishing
+
+ calls.
+
+
+ Calling `result` will resolve the future by returning the message
+
+ ID, unless an error occurs.
+
+
+ '
+ syntax:
+ content: Future()
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.publisher.futures.Future
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: Future
+ source:
+ id: Future
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
+ startLine: 26
+ summary: 'Initializes the future. Should not be called by clients.
+
+
+ '
+ syntax:
+ content: Future()
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.add_done_callback
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: add_done_callback
+ source:
+ id: add_done_callback
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
+ startLine: 69
+ summary: 'Attach a callable that will be called when the future finishes.
+
+ '
+ syntax:
+ content: "add_done_callback(\n callback: typing.Callable[[pubsub_v1.publisher.futures.Future],\
+ \ typing.Any]\n) -> None"
+ parameters:
+ - description: A callable that will be called with this future as its only argument
+ when the future completes or is cancelled. The callable will always be called
+ by a thread in the same process in which it was added. If the future has already
+ completed or been cancelled then the callable will be called immediately.
+ These callables are called in the order that they were added.
+ id: callback
+ var_type: typing.Callable[[pubsub_v1.publisher.futures.Future], typing.Any]
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.add_done_callback
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.cancel
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: cancel
+ source:
+ id: cancel
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
+ startLine: 34
+ summary: 'Actions in Pub/Sub generally may not be canceled.
+
+
+ This method always returns `False`.
+
+
+ '
+ syntax:
+ content: cancel() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.cancel
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.cancelled
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: cancelled
+ source:
+ id: cancelled
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
+ startLine: 41
+ summary: 'Actions in Pub/Sub generally may not be canceled.
+
+
+ This method always returns `False`.
+
+
+ '
+ syntax:
+ content: cancelled() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.cancelled
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.done
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: done
+ source:
+ id: done
+ path: concurrent/futures/_base.py
+ startLine: 395
+ summary: 'Return True if the future was cancelled or finished executing.
+
+
+ '
+ syntax:
+ content: done()
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.done
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.exception
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: exception
+ source:
+ id: exception
+ path: concurrent/futures/_base.py
+ startLine: 465
+ summary: 'Return the exception raised by the call that the future represents.
+
+ '
+ syntax:
+ content: exception(timeout=None)
+ exceptions:
+ - description: If the future was cancelled.
+ var_type: CancelledError
+ - description: If the future didn't finish executing before the given timeout.
+ var_type: TimeoutError
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.exception
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.result
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: result
+ source:
+ id: result
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
+ startLine: 48
+ summary: 'Return the message ID or raise an exception.
+
+
+ This blocks until the message has been published successfully and
+
+ returns the message ID unless an exception is raised.
+
+ '
+ syntax:
+ content: 'result(timeout: typing.Optional[typing.Union[int, float]] = None) ->
+ str'
+ exceptions:
+ - description: If the request times out.
+ var_type: concurrent.futures.TimeoutError
+ - description: For undefined exceptions in the underlying call execution.
+ var_type: Exception
+ parameters:
+ - defaultValue: None
+ description: The number of seconds before this call times out and raises TimeoutError.
+ id: timeout
+ var_type: typing.Union[int, float]
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.result
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.running
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: running
+ source:
+ id: running
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 33
+ summary: 'Return `True` if the associated Pub/Sub action has not yet completed.
+
+
+ '
+ syntax:
+ content: running() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.running
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.set_exception
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: set_exception
+ source:
+ id: set_exception
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 50
+ summary: 'Set the result of the future as being the given exception.
+
+
+ Do not use this method, it should only be used internally by the library and its
+
+ unit tests.
+
+
+ '
+ syntax:
+ content: 'set_exception(exception: typing.Optional[BaseException])'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.set_exception
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.set_result
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: set_result
+ source:
+ id: set_result
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 42
+ summary: 'Set the return value of work associated with the future.
+
+
+ Do not use this method, it should only be used internally by the library and its
+
+ unit tests.
+
+
+ '
+ syntax:
+ content: 'set_result(result: typing.Any)'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.set_result
+- attributes: []
+ class: google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures.Future.set_running_or_notify_cancel
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: set_running_or_notify_cancel
+ source:
+ id: set_running_or_notify_cancel
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 37
+ summary: 'Mark the future as running or process any cancel notifications.
+
+
+ Should only be used by Executor implementations and unit tests.
+
+
+ If the future has been cancelled (cancel() was called and returned
+
+ True) then any threads waiting on the future completing (though calls
+
+ to as_completed() or wait()) are notified and False is returned.
+
+
+ If the future was not cancelled then it is put in the running state
+
+ (future calls to running() will return True) and True is returned.
+
+
+ This method should be called by Executor implementations before
+
+ executing the work associated with this future. If this method returns
+
+ False then the work should not be executed.
+
+ '
+ syntax:
+ content: set_running_or_notify_cancel() -> typing.NoReturn
+ exceptions:
+ - description: if this method was already called or if set_result() or set_exception()
+ was called.
+ var_type: RuntimeError
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.set_running_or_notify_cancel
+references:
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future
+ isExternal: false
+ name: Future
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.add_done_callback
+ isExternal: false
+ name: add_done_callback
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.add_done_callback
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.cancel
+ isExternal: false
+ name: cancel
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.cancel
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.cancelled
+ isExternal: false
+ name: cancelled
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.cancelled
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.done
+ isExternal: false
+ name: done
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.done
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.exception
+ isExternal: false
+ name: exception
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.exception
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.result
+ isExternal: false
+ name: result
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.result
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.running
+ isExternal: false
+ name: running
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.running
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.set_exception
+ isExternal: false
+ name: set_exception
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.set_exception
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.set_result
+ isExternal: false
+ name: set_result
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.set_result
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future.set_running_or_notify_cancel
+ isExternal: false
+ name: set_running_or_notify_cancel
+ parent: google.cloud.pubsub_v1.publisher.futures.Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future.set_running_or_notify_cancel
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.futures.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.futures.yml
new file mode 100644
index 000000000000..2b25479d359c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.publisher.futures.yml
@@ -0,0 +1,24 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.publisher.futures.Future
+ fullName: google.cloud.pubsub_v1.publisher.futures
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.publisher.futures
+ name: publisher.futures
+ source:
+ id: futures
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/publisher/futures.py
+ startLine: 0
+ summary: API documentation for `pubsub_v1.publisher.futures` module.
+ syntax: {}
+ type: module
+ uid: google.cloud.pubsub_v1.publisher.futures
+references:
+- fullName: google.cloud.pubsub_v1.publisher.futures.Future
+ isExternal: false
+ name: Future
+ parent: google.cloud.pubsub_v1.publisher.futures
+ uid: google.cloud.pubsub_v1.publisher.futures.Future
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.client.Client.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.client.Client.yml
new file mode 100644
index 000000000000..f95ec84d0310
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.client.Client.yml
@@ -0,0 +1,2194 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.subscriber.client.Client
+ - google.cloud.pubsub_v1.subscriber.client.Client.acknowledge
+ - google.cloud.pubsub_v1.subscriber.client.Client.api
+ - google.cloud.pubsub_v1.subscriber.client.Client.close
+ - google.cloud.pubsub_v1.subscriber.client.Client.closed
+ - google.cloud.pubsub_v1.subscriber.client.Client.common_billing_account_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.common_folder_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.common_location_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.common_organization_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.common_project_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.create_snapshot
+ - google.cloud.pubsub_v1.subscriber.client.Client.create_subscription
+ - google.cloud.pubsub_v1.subscriber.client.Client.delete_snapshot
+ - google.cloud.pubsub_v1.subscriber.client.Client.delete_subscription
+ - google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_file
+ - google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_info
+ - google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_json
+ - google.cloud.pubsub_v1.subscriber.client.Client.get_iam_policy
+ - google.cloud.pubsub_v1.subscriber.client.Client.get_mtls_endpoint_and_cert_source
+ - google.cloud.pubsub_v1.subscriber.client.Client.get_snapshot
+ - google.cloud.pubsub_v1.subscriber.client.Client.get_subscription
+ - google.cloud.pubsub_v1.subscriber.client.Client.list_snapshots
+ - google.cloud.pubsub_v1.subscriber.client.Client.list_subscriptions
+ - google.cloud.pubsub_v1.subscriber.client.Client.modify_ack_deadline
+ - google.cloud.pubsub_v1.subscriber.client.Client.modify_push_config
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_common_billing_account_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_common_folder_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_common_location_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_common_organization_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_common_project_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_snapshot_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_subscription_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.parse_topic_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.pull
+ - google.cloud.pubsub_v1.subscriber.client.Client.seek
+ - google.cloud.pubsub_v1.subscriber.client.Client.set_iam_policy
+ - google.cloud.pubsub_v1.subscriber.client.Client.snapshot_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.streaming_pull
+ - google.cloud.pubsub_v1.subscriber.client.Client.subscribe
+ - google.cloud.pubsub_v1.subscriber.client.Client.subscription_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.target
+ - google.cloud.pubsub_v1.subscriber.client.Client.test_iam_permissions
+ - google.cloud.pubsub_v1.subscriber.client.Client.topic_path
+ - google.cloud.pubsub_v1.subscriber.client.Client.transport
+ - google.cloud.pubsub_v1.subscriber.client.Client.update_snapshot
+ - google.cloud.pubsub_v1.subscriber.client.Client.update_subscription
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: Client
+ source:
+ id: Client
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
+ startLine: 46
+ summary: 'A subscriber client for Google Cloud Pub/Sub.
+
+
+ This creates an object that is capable of subscribing to messages.
+
+ Generally, you can instantiate this client with no arguments, and you
+
+ get sensible defaults.
+
+ '
+ syntax:
+ content: 'Client(**kwargs: typing.Any)'
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.subscriber.client.Client
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: Client
+ source:
+ id: Client
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
+ startLine: 46
+ summary: 'Instantiates the subscriber client.
+
+ '
+ syntax:
+ content: 'Client(**kwargs: typing.Any)'
+ exceptions:
+ - description: If mutual TLS transport creation failed for any reason.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - description: The authorization credentials to attach to requests. These credentials
+ identify the application to the service; if none are specified, the client
+ will attempt to ascertain the credentials from the environment.
+ id: credentials
+ var_type: Optional[google.auth.credentials.Credentials]
+ - description: The transport to use. If set to None, a transport is chosen automatically.
+ id: transport
+ var_type: Union[str, SubscriberTransport]
+ - description: 'Custom options for the client. It won''t take effect if a transport
+ instance is provided. (1) The api_endpoint property can be used
+ to override the default endpoint provided by the client. GOOGLE_API_USE_MTLS_ENDPOINT
+ environment variable can also be used to override the endpoint: "always" (always
+ use the default mTLS endpoint), "never" (always use the default regular endpoint)
+ and "auto" (auto switch to the default mTLS endpoint if client certificate
+ is present, this is the default value). However, the api_endpoint
+ property takes precedence if provided. (2) If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ environment variable is "true", then the client_cert_source property
+ can be used to provide client certificate for mutual TLS transport. If not
+ provided, the default SSL client certificate will be used if present. If GOOGLE_API_USE_CLIENT_CERTIFICATE
+ is "false" or not set, no client certificate will be used.'
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ - description: The client info used to send a user-agent string along with API
+ requests. If None, then default info will be used. Generally,
+ you only need to set this if you're developing your own client library.
+ id: client_info
+ var_type: google.api_core.gapic_v1.client_info.ClientInfo
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.acknowledge
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: acknowledge
+ source:
+ id: acknowledge
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1203
+ summary: "Acknowledges the messages associated with the `ack_ids` in the\n`AcknowledgeRequest`.\
+ \ The Pub/Sub system can remove the\nrelevant messages from the subscription.\n\
+ \nAcknowledging a message whose ack deadline has expired may\nsucceed, but such\
+ \ a message may be redelivered later.\nAcknowledging a message more than once\
+ \ will not result in an\nerror.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_acknowledge():\n # Create a client\n\
+ \ client = pubsub_v1.SubscriberClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.AcknowledgeRequest(\n subscription=\"subscription_value\"\
+ ,\n ack_ids=['ack_ids_value1', 'ack_ids_value2'],\n )\n\n # Make\
+ \ the request\n client.acknowledge(request=request)\n```\n"
+ syntax:
+ content: "acknowledge(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.AcknowledgeRequest,\
+ \ dict]\n ] = None,\n *,\n subscription: typing.Optional[str] = None,\n\
+ \ ack_ids: typing.Optional[typing.Sequence[str]] = None,\n retry: typing.Union[\n\
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ None"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the Acknowledge method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.AcknowledgeRequest, dict]
+ - description: Required. The subscription whose message is being acknowledged.
+ Format is projects/{project}/subscriptions/{sub}. This corresponds
+ to the subscription field on the request instance;
+ if request is provided, this should not be set.
+ id: subscription
+ var_type: str
+ - description: Required. The acknowledgment ID for the messages being acknowledged
+ that was returned by the Pub/Sub system in the Pull response.
+ Must not be empty. This corresponds to the ack_ids field on the
+ request instance; if request is provided, this should
+ not be set.
+ id: ack_ids
+ var_type: Sequence[str]
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.acknowledge
+- &id001
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.api
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: api
+ source:
+ id: api
+ path: null
+ startLine: null
+ summary: "The underlying gapic API client.\n\n.. versionchanged:: 2.10.0\n Instead\
+ \ of a GAPIC `SubscriberClient` client instance, this property is a\n proxy\
+ \ object to it with the same interface.\n\n\ndeprecated: \n\
+ Use the GAPIC methods and properties on the client instance directly\ninstead\
+ \ of through the `api` attribute.\n "
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.api
+- *id001
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.close
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: close
+ source:
+ id: close
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
+ startLine: 271
+ summary: 'Close the underlying channel to release socket resources.
+
+
+ After a channel has been closed, the client instance cannot be used
+
+ anymore.
+
+
+ This method is idempotent.
+
+
+ '
+ syntax:
+ content: close() -> None
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.close
+- &id002
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.closed
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: closed
+ source:
+ id: closed
+ path: null
+ startLine: null
+ summary: 'Return whether the client has been closed and cannot be used anymore.
+
+
+ .. versionadded:: 2.8.0
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.closed
+- *id002
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: common_billing_account_path
+ source:
+ id: common_billing_account_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 248
+ summary: 'Returns a fully-qualified billing_account string.
+
+
+ '
+ syntax:
+ content: 'common_billing_account_path(billing_account: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_billing_account_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_folder_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: common_folder_path
+ source:
+ id: common_folder_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 263
+ summary: 'Returns a fully-qualified folder string.
+
+
+ '
+ syntax:
+ content: 'common_folder_path(folder: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_folder_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_location_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: common_location_path
+ source:
+ id: common_location_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 308
+ summary: 'Returns a fully-qualified location string.
+
+
+ '
+ syntax:
+ content: 'common_location_path(project: str, location: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_location_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_organization_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: common_organization_path
+ source:
+ id: common_organization_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 278
+ summary: 'Returns a fully-qualified organization string.
+
+
+ '
+ syntax:
+ content: 'common_organization_path(organization: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_organization_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_project_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: common_project_path
+ source:
+ id: common_project_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 293
+ summary: 'Returns a fully-qualified project string.
+
+
+ '
+ syntax:
+ content: 'common_project_path(project: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_project_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.create_snapshot
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: create_snapshot
+ source:
+ id: create_snapshot
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1892
+ summary: "Creates a snapshot from the requested subscription. Snapshots\nare used\
+ \ in\n`Seek `__\noperations,\
+ \ which allow you to manage message acknowledgments in\nbulk. That is, you can\
+ \ set the acknowledgment state of messages\nin an existing subscription to the\
+ \ state captured by a snapshot.\nIf the snapshot already exists, returns `ALREADY_EXISTS`.\
+ \ If\nthe requested subscription doesn't exist, returns `NOT_FOUND`.\nIf the backlog\
+ \ in the subscription is too old -- and the\nresulting snapshot would expire in\
+ \ less than 1 hour -- then\n`FAILED_PRECONDITION` is returned. See also the\n\
+ `Snapshot.expire_time` field. If the name is not provided in\nthe request, the\
+ \ server will assign a random name for this\nsnapshot on the same project as the\
+ \ subscription, conforming to\nthe [resource name format]\n(https://cloud.google.com/pubsub/docs/admin#resource_names).\
+ \ The\ngenerated name is populated in the returned Snapshot object.\nNote that\
+ \ for REST API requests, you must specify a name in the\nrequest.\n\n```python\n\
+ # This snippet has been automatically generated and should be regarded as a\n\
+ # code template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_create_snapshot():\n # Create a\
+ \ client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.CreateSnapshotRequest(\n name=\"\
+ name_value\",\n subscription=\"subscription_value\",\n )\n\n # Make\
+ \ the request\n response = client.create_snapshot(request=request)\n\n #\
+ \ Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "create_snapshot(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.CreateSnapshotRequest,\
+ \ dict]\n ] = None,\n *,\n name: typing.Optional[str] = None,\n \
+ \ subscription: typing.Optional[str] = None,\n retry: typing.Union[\n \
+ \ google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.pubsub_v1.types.Snapshot"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the CreateSnapshot
+ method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.CreateSnapshotRequest, dict]
+ - description: Required. User-provided name for this snapshot. If the name is
+ not provided in the request, the server will assign a random name for this
+ snapshot on the same project as the subscription. Note that for REST API requests,
+ you must specify a name. See the resource name rules. Format is projects/{project}/snapshots/{snap}.
+ This corresponds to the name field on the request
+ instance; if request is provided, this should not be set.
+ id: name
+ var_type: str
+ - description: 'Required. The subscription whose backlog the snapshot retains.
+ Specifically, the created snapshot is guaranteed to retain: (a) The existing
+ backlog on the subscription. More precisely, this is defined as the messages
+ in the subscription''s backlog that are unacknowledged upon the successful
+ completion of the CreateSnapshot request; as well as: (b) Any
+ messages published to the subscription''s topic following the successful completion
+ of the CreateSnapshot request. Format is projects/{project}/subscriptions/{sub}.
+ This corresponds to the subscription field on the request
+ instance; if request is provided, this should not be set.'
+ id: subscription
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A snapshot resource. Snapshots are used in [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in bulk. That
+ is, you can set the acknowledgment state of messages in an existing subscription
+ to the state captured by a snapshot.
+ var_type: google.pubsub_v1.types.Snapshot
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.create_snapshot
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.create_subscription
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: create_subscription
+ source:
+ id: create_subscription
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 500
+ summary: "Creates a subscription to a given topic. See the [resource name\nrules]\n\
+ (https://cloud.google.com/pubsub/docs/admin#resource_names). If\nthe subscription\
+ \ already exists, returns `ALREADY_EXISTS`. If\nthe corresponding topic doesn't\
+ \ exist, returns `NOT_FOUND`.\n\nIf the name is not provided in the request, the\
+ \ server will\nassign a random name for this subscription on the same project\n\
+ as the topic, conforming to the [resource name format]\n(https://cloud.google.com/pubsub/docs/admin#resource_names).\
+ \ The\ngenerated name is populated in the returned Subscription object.\nNote\
+ \ that for REST API requests, you must specify a name in the\nrequest.\n\n```python\n\
+ # This snippet has been automatically generated and should be regarded as a\n\
+ # code template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_create_subscription():\n # Create\
+ \ a client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.Subscription(\n name=\"name_value\"\
+ ,\n topic=\"topic_value\",\n )\n\n # Make the request\n response\
+ \ = client.create_subscription(request=request)\n\n # Handle the response\n\
+ \ print(response)\n```\n"
+ syntax:
+ content: "create_subscription(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.Subscription,\
+ \ dict]\n ] = None,\n *,\n name: typing.Optional[str] = None,\n \
+ \ topic: typing.Optional[str] = None,\n push_config: typing.Optional[google.cloud.pubsub_v1.types.PushConfig]\
+ \ = None,\n ack_deadline_seconds: typing.Optional[int] = None,\n retry:\
+ \ typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.pubsub_v1.types.Subscription"
+ parameters:
+ - defaultValue: None
+ description: The request object. A subscription resource.
+ id: request
+ var_type: Union[google.pubsub_v1.types.Subscription, dict]
+ - description: Required. The name of the subscription. It must have the format
+ "projects/{project}/subscriptions/{subscription}". {subscription}
+ must start with a letter, and contain only letters ([A-Za-z]),
+ numbers ([0-9]), dashes (-), underscores (_),
+ periods (.), tildes (+)
+ or percent signs (%). It must be between 3 and 255
+ characters in length, and it must not start with "goog". This
+ corresponds to the name field on the request instance;
+ if request` is provided, this should not be set.
+ id: name
+ var_type: str
+ - description: Required. The name of the topic from which this subscription is
+ receiving messages. Format is projects/{project}/topics/{topic}.
+ The value of this field will be _deleted-topic_ if the topic
+ has been deleted. This corresponds to the topic field on the
+ request instance; if request is provided, this should
+ not be set.
+ id: topic
+ var_type: str
+ - description: If push delivery is used with this subscription, this field is
+ used to configure it. Either pushConfig or bigQueryConfig
+ can be set, but not both. If both are empty, then the subscriber will pull
+ and ack messages using API methods. This corresponds to the push_config
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: push_config
+ var_type: google.pubsub_v1.types.PushConfig
+ - description: The approximate amount of time (on a best-effort basis) Pub/Sub
+ waits for the subscriber to acknowledge receipt before resending the message.
+ In the interval after the message is delivered and before it is acknowledged,
+ it is considered to be outstanding. During that time period, the message will
+ not be redelivered (on a best-effort basis). For pull subscriptions, this
+ value is used as the initial value for the ack deadline. To override this
+ value for a given message, call ModifyAckDeadline with the corresponding
+ ack_id if using non-streaming pull or send the ack_id
+ in a StreamingModifyAckDeadlineRequest if using streaming pull.
+ The minimum custom deadline you can specify is 10 seconds. The maximum custom
+ deadline you can specify is 600 seconds (10 minutes). If this parameter is
+ 0, a default value of 10 seconds is used. For push delivery, this value is
+ also used to set the request timeout for the call to the push endpoint. If
+ the subscriber never acknowledges the message, the Pub/Sub system will eventually
+ redeliver the message. This corresponds to the ack_deadline_seconds
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: ack_deadline_seconds
+ var_type: int
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A subscription resource.
+ var_type: google.pubsub_v1.types.Subscription
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.create_subscription
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.delete_snapshot
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: delete_snapshot
+ source:
+ id: delete_snapshot
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 2133
+ summary: "Removes an existing snapshot. Snapshots are used in [Seek]\n(https://cloud.google.com/pubsub/docs/replay-overview)\n\
+ operations, which allow you to manage message acknowledgments in\nbulk. That is,\
+ \ you can set the acknowledgment state of messages\nin an existing subscription\
+ \ to the state captured by a snapshot.\nWhen the snapshot is deleted, all messages\
+ \ retained in the\nsnapshot are immediately dropped. After a snapshot is deleted,\
+ \ a\nnew one may be created with the same name, but the new one has\nno association\
+ \ with the old snapshot or its subscription, unless\nthe same subscription is\
+ \ specified.\n\n```python\n# This snippet has been automatically generated and\
+ \ should be regarded as a\n# code template only.\n# It will require modifications\
+ \ to work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_delete_snapshot():\n # Create a\
+ \ client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.DeleteSnapshotRequest(\n snapshot=\"\
+ snapshot_value\",\n )\n\n # Make the request\n client.delete_snapshot(request=request)\n\
+ ```\n"
+ syntax:
+ content: "delete_snapshot(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.DeleteSnapshotRequest,\
+ \ dict]\n ] = None,\n *,\n snapshot: typing.Optional[str] = None,\n\
+ \ retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ None"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the DeleteSnapshot
+ method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.DeleteSnapshotRequest, dict]
+ - description: Required. The name of the snapshot to delete. Format is projects/{project}/snapshots/{snap}.
+ This corresponds to the snapshot field on the request
+ instance; if request is provided, this should not be set.
+ id: snapshot
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.delete_snapshot
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.delete_subscription
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: delete_subscription
+ source:
+ id: delete_subscription
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 980
+ summary: "Deletes an existing subscription. All messages retained in the\nsubscription\
+ \ are immediately dropped. Calls to `Pull` after\ndeletion will return `NOT_FOUND`.\
+ \ After a subscription is\ndeleted, a new one may be created with the same name,\
+ \ but the\nnew one has no association with the old subscription or its\ntopic\
+ \ unless the same topic is specified.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_delete_subscription():\n # Create\
+ \ a client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.DeleteSubscriptionRequest(\n subscription=\"\
+ subscription_value\",\n )\n\n # Make the request\n client.delete_subscription(request=request)\n\
+ ```\n"
+ syntax:
+ content: "delete_subscription(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.DeleteSubscriptionRequest,\
+ \ dict]\n ] = None,\n *,\n subscription: typing.Optional[str] = None,\n\
+ \ retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ None"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the DeleteSubscription method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.DeleteSubscriptionRequest, dict]
+ - description: Required. The subscription to delete. Format is projects/{project}/subscriptions/{sub}.
+ This corresponds to the subscription field on the request
+ instance; if request is provided, this should not be set.
+ id: subscription
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.delete_subscription
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_file
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: from_service_account_file
+ source:
+ id: from_service_account_file
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
+ startLine: 91
+ summary: 'Creates an instance of this client using the provided credentials
+
+ file.
+
+ '
+ syntax:
+ content: "from_service_account_file(\n filename: str, **kwargs: typing.Any\n\
+ ) -> google.cloud.pubsub_v1.subscriber.client.Client"
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_file
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_info
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: from_service_account_info
+ source:
+ id: from_service_account_info
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 148
+ summary: "Creates an instance of this client using the provided credentials\n \
+ \ info.\n"
+ syntax:
+ content: 'from_service_account_info(info: dict, *args, **kwargs)'
+ parameters:
+ - description: The service account private key info.
+ id: info
+ var_type: dict
+ returns:
+ - description: The constructed client.
+ var_type: SubscriberClient
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_info
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_json
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: from_service_account_json
+ source:
+ id: from_service_account_json
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
+ startLine: 91
+ summary: 'Creates an instance of this client using the provided credentials
+
+ file.
+
+ '
+ syntax:
+ content: "from_service_account_json(\n filename: str, **kwargs: typing.Any\n\
+ ) -> google.cloud.pubsub_v1.subscriber.client.Client"
+ parameters:
+ - description: The path to the service account private key json file.
+ id: filename
+ var_type: str
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_json
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_iam_policy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: get_iam_policy
+ source:
+ id: get_iam_policy
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 2453
+ summary: 'Gets the IAM access control policy for a function.
+
+
+ Returns an empty policy if the function exists and does not have a
+
+ policy set.
+
+ '
+ syntax:
+ content: "get_iam_policy(\n request: typing.Optional[google.iam.v1.iam_policy_pb2.GetIamPolicyRequest]\
+ \ = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.iam.v1.policy_pb2.Policy"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request message for GetIamPolicy
+ method.
+ id: request
+ var_type: .iam_policy_pb2.GetIamPolicyRequest
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: 'Defines an Identity and Access Management (IAM) policy. It is
+ used to specify access control policies for Cloud Platform resources. A Policy
+ is a collection of bindings. A binding binds one
+ or more members to a single role. Members can be
+ user accounts, service accounts, Google groups, and domains (such as G Suite).
+ A role is a named list of permissions (defined by IAM or configured
+ by users). A binding can optionally specify a condition,
+ which is a logic expression that further constrains the role binding based
+ on attributes about the request and/or target resource. **JSON Example** ::
+ { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members":
+ [ "user:mike@example.com", "group:admins@example.com", "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role":
+ "roles/resourcemanager.organizationViewer", "members": ["user:eve@example.com"],
+ "condition": { "title": "expirable access", "description": "Does not grant
+ access after Sep 2020", "expression": "request.time < timestamp(''2020-10-01T00:00:00.000Z'')",
+ } } ] } **YAML Example** :: bindings: - members: - user:mike@example.com -
+ group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer condition: title: expirable
+ access description: Does not grant access after Sep 2020 expression: request.time
+ < timestamp(''2020-10-01T00:00:00.000Z'') For a description of IAM and its
+ features, see the IAM developer''s guide __.'
+ var_type: .policy_pb2.Policy
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_iam_policy
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_mtls_endpoint_and_cert_source
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: get_mtls_endpoint_and_cert_source
+ source:
+ id: get_mtls_endpoint_and_cert_source
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 325
+ summary: 'Return the API endpoint and client cert source for mutual TLS.
+
+
+ The client cert source is determined in the following order:
+
+ (1) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is not "true",
+ the
+
+ client cert source is None.
+
+ (2) if `client_options.client_cert_source` is provided, use the provided one;
+ if the
+
+ default client cert source exists, use the default one; otherwise the client cert
+
+ source is None.
+
+
+ The API endpoint is determined in the following order:
+
+ (1) if `client_options.api_endpoint` if provided, use the provided one.
+
+ (2) if `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable is "always", use
+ the
+
+ default mTLS endpoint; if the environment variabel is "never", use the default
+ API
+
+ endpoint; otherwise if client cert source exists, use the default mTLS endpoint,
+ otherwise
+
+ use the default API endpoint.
+
+
+ More details can be found at https://google.aip.dev/auth/4114.
+
+ '
+ syntax:
+ content: "get_mtls_endpoint_and_cert_source(\n client_options: typing.Optional[\n\
+ \ google.api_core.client_options.ClientOptions\n ] = None,\n)"
+ exceptions:
+ - description: If any errors happen.
+ var_type: google.auth.exceptions.MutualTLSChannelError
+ parameters:
+ - defaultValue: None
+ description: Custom options for the client. Only the api_endpoint
+ and client_cert_source properties may be used in this method.
+ id: client_options
+ var_type: google.api_core.client_options.ClientOptions
+ returns:
+ - description: returns the API endpoint and the client cert source to use.
+ var_type: Tuple[str, Callable[[], Tuple[bytes, bytes]]]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_mtls_endpoint_and_cert_source
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_snapshot
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: get_snapshot
+ source:
+ id: get_snapshot
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1663
+ summary: "Gets the configuration details of a snapshot.\nSnapshots are used in Seek\noperations,\
+ \ which allow you to manage message\nacknowledgments in bulk. That is, you can\
+ \ set the\nacknowledgment state of messages in an existing\nsubscription to the\
+ \ state captured by a snapshot.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_get_snapshot():\n # Create a client\n\
+ \ client = pubsub_v1.SubscriberClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.GetSnapshotRequest(\n snapshot=\"snapshot_value\"\
+ ,\n )\n\n # Make the request\n response = client.get_snapshot(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "get_snapshot(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.GetSnapshotRequest,\
+ \ dict]\n ] = None,\n *,\n snapshot: typing.Optional[str] = None,\n\
+ \ retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.pubsub_v1.types.Snapshot"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the GetSnapshot method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.GetSnapshotRequest, dict]
+ - description: Required. The name of the snapshot to get. Format is projects/{project}/snapshots/{snap}.
+ This corresponds to the snapshot field on the request
+ instance; if request is provided, this should not be set.
+ id: snapshot
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A snapshot resource. Snapshots are used in [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in bulk. That
+ is, you can set the acknowledgment state of messages in an existing subscription
+ to the state captured by a snapshot.
+ var_type: google.pubsub_v1.types.Snapshot
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_snapshot
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_subscription
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: get_subscription
+ source:
+ id: get_subscription
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 677
+ summary: "Gets the configuration details of a subscription.\n\n```python\n# This\
+ \ snippet has been automatically generated and should be regarded as a\n# code\
+ \ template only.\n# It will require modifications to work:\n# - It may require\
+ \ correct/in-range values for request initialization.\n# - It may require specifying\
+ \ regional endpoints when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_get_subscription():\n # Create a\
+ \ client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.GetSubscriptionRequest(\n subscription=\"\
+ subscription_value\",\n )\n\n # Make the request\n response = client.get_subscription(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "get_subscription(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.GetSubscriptionRequest,\
+ \ dict]\n ] = None,\n *,\n subscription: typing.Optional[str] = None,\n\
+ \ retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.pubsub_v1.types.Subscription"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the GetSubscription method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.GetSubscriptionRequest, dict]
+ - description: Required. The name of the subscription to get. Format is projects/{project}/subscriptions/{sub}.
+ This corresponds to the subscription field on the request
+ instance; if request is provided, this should not be set.
+ id: subscription
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A subscription resource.
+ var_type: google.pubsub_v1.types.Subscription
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_subscription
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.list_snapshots
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: list_snapshots
+ source:
+ id: list_snapshots
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1774
+ summary: "Lists the existing snapshots. Snapshots are used in\n`Seek `__\n\
+ operations, which allow you to manage message acknowledgments in\nbulk. That is,\
+ \ you can set the acknowledgment state of messages\nin an existing subscription\
+ \ to the state captured by a snapshot.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_list_snapshots():\n # Create a client\n\
+ \ client = pubsub_v1.SubscriberClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.ListSnapshotsRequest(\n project=\"project_value\"\
+ ,\n )\n\n # Make the request\n page_result = client.list_snapshots(request=request)\n\
+ \n # Handle the response\n for response in page_result:\n print(response)\n\
+ ```\n"
+ syntax:
+ content: "list_snapshots(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.ListSnapshotsRequest,\
+ \ dict]\n ] = None,\n *,\n project: typing.Optional[str] = None,\n\
+ \ retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the ListSnapshots
+ method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.ListSnapshotsRequest, dict]
+ - description: Required. The name of the project in which to list snapshots. Format
+ is projects/{project-id}. This corresponds to the project
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: project
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the ListSnapshots method. Iterating over this object
+ will yield results and resolve additional pages automatically.
+ var_type: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.list_snapshots
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.list_subscriptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: list_subscriptions
+ source:
+ id: list_subscriptions
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 866
+ summary: "Lists matching subscriptions.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_list_subscriptions():\n # Create\
+ \ a client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.ListSubscriptionsRequest(\n project=\"\
+ project_value\",\n )\n\n # Make the request\n page_result = client.list_subscriptions(request=request)\n\
+ \n # Handle the response\n for response in page_result:\n print(response)\n\
+ ```\n"
+ syntax:
+ content: "list_subscriptions(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.ListSubscriptionsRequest,\
+ \ dict]\n ] = None,\n *,\n project: typing.Optional[str] = None,\n\
+ \ retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the ListSubscriptions
+ method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.ListSubscriptionsRequest, dict]
+ - description: Required. The name of the project in which to list subscriptions.
+ Format is projects/{project-id}. This corresponds to the project
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: project
+ var_type: str
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the ListSubscriptions method. Iterating over this
+ object will yield results and resolve additional pages automatically.
+ var_type: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.list_subscriptions
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.modify_ack_deadline
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: modify_ack_deadline
+ source:
+ id: modify_ack_deadline
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1077
+ summary: "Modifies the ack deadline for a specific message. This method is\nuseful\
+ \ to indicate that more time is needed to process a message\nby the subscriber,\
+ \ or to make the message available for\nredelivery if the processing was interrupted.\
+ \ Note that this\ndoes not modify the subscription-level `ackDeadlineSeconds`\n\
+ used for subsequent messages.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_modify_ack_deadline():\n # Create\
+ \ a client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.ModifyAckDeadlineRequest(\n subscription=\"\
+ subscription_value\",\n ack_ids=['ack_ids_value1', 'ack_ids_value2'],\n\
+ \ ack_deadline_seconds=2066,\n )\n\n # Make the request\n client.modify_ack_deadline(request=request)\n\
+ ```\n"
+ syntax:
+ content: "modify_ack_deadline(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest,\
+ \ dict]\n ] = None,\n *,\n subscription: typing.Optional[str] = None,\n\
+ \ ack_ids: typing.Optional[typing.Sequence[str]] = None,\n ack_deadline_seconds:\
+ \ typing.Optional[int] = None,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> None"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the ModifyAckDeadline method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.ModifyAckDeadlineRequest, dict]
+ - description: Required. The name of the subscription. Format is projects/{project}/subscriptions/{sub}.
+ This corresponds to the subscription field on the request
+ instance; if request is provided, this should not be set.
+ id: subscription
+ var_type: str
+ - description: Required. List of acknowledgment IDs. This corresponds to the ack_ids
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: ack_ids
+ var_type: Sequence[str]
+ - description: Required. The new ack deadline with respect to the time this request
+ was sent to the Pub/Sub system. For example, if the value is 10, the new ack
+ deadline will expire 10 seconds after the ModifyAckDeadline call
+ was made. Specifying zero might immediately make the message available for
+ delivery to another subscriber client. This typically results in an increase
+ in the rate of message redeliveries (that is, duplicates). The minimum deadline
+ you can specify is 0 seconds. The maximum deadline you can specify is 600
+ seconds (10 minutes). This corresponds to the ack_deadline_seconds
+ field on the request instance; if request is provided,
+ this should not be set.
+ id: ack_deadline_seconds
+ var_type: int
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.modify_ack_deadline
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.modify_push_config
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: modify_push_config
+ source:
+ id: modify_push_config
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1550
+ summary: "Modifies the `PushConfig` for a specified subscription.\n\nThis may be\
+ \ used to change a push subscription to a pull one\n(signified by an empty `PushConfig`)\
+ \ or vice versa, or change\nthe endpoint URL and other attributes of a push subscription.\n\
+ Messages will accumulate for delivery continuously through the\ncall regardless\
+ \ of changes to the `PushConfig`.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_modify_push_config():\n # Create\
+ \ a client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.ModifyPushConfigRequest(\n subscription=\"\
+ subscription_value\",\n )\n\n # Make the request\n client.modify_push_config(request=request)\n\
+ ```\n"
+ syntax:
+ content: "modify_push_config(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.ModifyPushConfigRequest,\
+ \ dict]\n ] = None,\n *,\n subscription: typing.Optional[str] = None,\n\
+ \ push_config: typing.Optional[google.cloud.pubsub_v1.types.PushConfig] =\
+ \ None,\n retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ None"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the ModifyPushConfig method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.ModifyPushConfigRequest, dict]
+ - description: Required. The name of the subscription. Format is projects/{project}/subscriptions/{sub}.
+ This corresponds to the subscription field on the request
+ instance; if request is provided, this should not be set.
+ id: subscription
+ var_type: str
+ - description: Required. The push configuration for future deliveries. An empty
+ pushConfig indicates that the Pub/Sub system should stop pushing
+ messages from the given subscription and allow messages to be pulled and acknowledged
+ - effectively pausing the subscription if Pull or StreamingPull
+ is not called. This corresponds to the push_config field on the
+ request instance; if request is provided, this should
+ not be set.
+ id: push_config
+ var_type: google.pubsub_v1.types.PushConfig
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.modify_push_config
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_billing_account_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_common_billing_account_path
+ source:
+ id: parse_common_billing_account_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 257
+ summary: 'Parse a billing_account path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_billing_account_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_billing_account_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_folder_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_common_folder_path
+ source:
+ id: parse_common_folder_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 272
+ summary: 'Parse a folder path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_folder_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_folder_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_location_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_common_location_path
+ source:
+ id: parse_common_location_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 319
+ summary: 'Parse a location path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_location_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_location_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_organization_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_common_organization_path
+ source:
+ id: parse_common_organization_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 287
+ summary: 'Parse a organization path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_organization_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_organization_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_project_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_common_project_path
+ source:
+ id: parse_common_project_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 302
+ summary: 'Parse a project path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_common_project_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_project_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_snapshot_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_snapshot_path
+ source:
+ id: parse_snapshot_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 206
+ summary: 'Parses a snapshot path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_snapshot_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_snapshot_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_subscription_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_subscription_path
+ source:
+ id: parse_subscription_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 223
+ summary: 'Parses a subscription path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_subscription_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_subscription_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_topic_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: parse_topic_path
+ source:
+ id: parse_topic_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 242
+ summary: 'Parses a topic path into its component segments.
+
+
+ '
+ syntax:
+ content: 'parse_topic_path(path: str) -> typing.Dict[str, str]'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_topic_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.pull
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: pull
+ source:
+ id: pull
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1314
+ summary: "Pulls messages from the server. The server may return\n`UNAVAILABLE` if\
+ \ there are too many concurrent pull requests\npending for the given subscription.\n\
+ \n```python\n# This snippet has been automatically generated and should be regarded\
+ \ as a\n# code template only.\n# It will require modifications to work:\n# - It\
+ \ may require correct/in-range values for request initialization.\n# - It may\
+ \ require specifying regional endpoints when creating the service\n# client\
+ \ as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_pull():\n # Create a client\n \
+ \ client = pubsub_v1.SubscriberClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.PullRequest(\n subscription=\"subscription_value\"\
+ ,\n max_messages=1277,\n )\n\n # Make the request\n response =\
+ \ client.pull(request=request)\n\n # Handle the response\n print(response)\n\
+ ```\n"
+ syntax:
+ content: "pull(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.PullRequest,\
+ \ dict]\n ] = None,\n *,\n subscription: typing.Optional[str] = None,\n\
+ \ return_immediately: typing.Optional[bool] = None,\n max_messages: typing.Optional[int]\
+ \ = None,\n retry: typing.Union[\n google.api_core.retry.Retry, google.api_core.gapic_v1.method._MethodDefault\n\
+ \ ] = _MethodDefault._DEFAULT_VALUE,\n timeout: typing.Optional[float]\
+ \ = None,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n) ->\
+ \ google.cloud.pubsub_v1.types.PullResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the Pull method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.PullRequest, dict]
+ - description: Required. The subscription from which messages should be pulled.
+ Format is projects/{project}/subscriptions/{sub}. This corresponds
+ to the subscription field on the request instance;
+ if request is provided, this should not be set.
+ id: subscription
+ var_type: str
+ - description: 'Optional. If this field set to true, the system will respond immediately
+ even if it there are no messages available to return in the Pull
+ response. Otherwise, the system may wait (for a bounded amount of time) until
+ at least one message is available, rather than returning no messages. Warning:
+ setting this field to true is discouraged because it adversely
+ impacts the performance of Pull operations. We recommend that
+ users do not set this field. This corresponds to the return_immediately
+ field on the request instance; if request is provided,
+ this should not be set.'
+ id: return_immediately
+ var_type: bool
+ - description: Required. The maximum number of messages to return for this request.
+ Must be a positive integer. The Pub/Sub system may return fewer than the number
+ specified. This corresponds to the max_messages field on the
+ request instance; if request is provided, this should
+ not be set.
+ id: max_messages
+ var_type: int
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the Pull method.
+ var_type: google.pubsub_v1.types.PullResponse
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.pull
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.seek
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: seek
+ source:
+ id: seek
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 2232
+ summary: "Seeks an existing subscription to a point in time or to a given\nsnapshot,\
+ \ whichever is provided in the request. Snapshots are\nused in [Seek]\n(https://cloud.google.com/pubsub/docs/replay-overview)\n\
+ operations, which allow you to manage message acknowledgments in\nbulk. That is,\
+ \ you can set the acknowledgment state of messages\nin an existing subscription\
+ \ to the state captured by a snapshot.\nNote that both the subscription and the\
+ \ snapshot must be on the\nsame topic.\n\n```python\n# This snippet has been automatically\
+ \ generated and should be regarded as a\n# code template only.\n# It will require\
+ \ modifications to work:\n# - It may require correct/in-range values for request\
+ \ initialization.\n# - It may require specifying regional endpoints when creating\
+ \ the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_seek():\n # Create a client\n \
+ \ client = pubsub_v1.SubscriberClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.SeekRequest(\n subscription=\"subscription_value\"\
+ ,\n )\n\n # Make the request\n response = client.seek(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "seek(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.SeekRequest,\
+ \ dict]\n ] = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.cloud.pubsub_v1.types.SeekResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the Seek method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.SeekRequest, dict]
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the Seek method (this response is empty).
+ var_type: google.pubsub_v1.types.SeekResponse
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.seek
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.set_iam_policy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: set_iam_policy
+ source:
+ id: set_iam_policy
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 2333
+ summary: 'Sets the IAM access control policy on the specified function.
+
+
+ Replaces any existing policy.
+
+ '
+ syntax:
+ content: "set_iam_policy(\n request: typing.Optional[google.iam.v1.iam_policy_pb2.SetIamPolicyRequest]\
+ \ = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.iam.v1.policy_pb2.Policy"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request message for SetIamPolicy
+ method.
+ id: request
+ var_type: .iam_policy_pb2.SetIamPolicyRequest
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: 'Defines an Identity and Access Management (IAM) policy. It is
+ used to specify access control policies for Cloud Platform resources. A Policy
+ is a collection of bindings. A binding binds one
+ or more members to a single role. Members can be
+ user accounts, service accounts, Google groups, and domains (such as G Suite).
+ A role is a named list of permissions (defined by IAM or configured
+ by users). A binding can optionally specify a condition,
+ which is a logic expression that further constrains the role binding based
+ on attributes about the request and/or target resource. **JSON Example** ::
+ { "bindings": [ { "role": "roles/resourcemanager.organizationAdmin", "members":
+ [ "user:mike@example.com", "group:admins@example.com", "domain:google.com",
+ "serviceAccount:my-project-id@appspot.gserviceaccount.com" ] }, { "role":
+ "roles/resourcemanager.organizationViewer", "members": ["user:eve@example.com"],
+ "condition": { "title": "expirable access", "description": "Does not grant
+ access after Sep 2020", "expression": "request.time < timestamp(''2020-10-01T00:00:00.000Z'')",
+ } } ] } **YAML Example** :: bindings: - members: - user:mike@example.com -
+ group:admins@example.com - domain:google.com - serviceAccount:my-project-id@appspot.gserviceaccount.com
+ role: roles/resourcemanager.organizationAdmin - members: - user:eve@example.com
+ role: roles/resourcemanager.organizationViewer condition: title: expirable
+ access description: Does not grant access after Sep 2020 expression: request.time
+ < timestamp(''2020-10-01T00:00:00.000Z'') For a description of IAM and its
+ features, see the IAM developer''s guide __.'
+ var_type: .policy_pb2.Policy
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.set_iam_policy
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.snapshot_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: snapshot_path
+ source:
+ id: snapshot_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 195
+ summary: 'Returns a fully-qualified snapshot string.
+
+
+ '
+ syntax:
+ content: 'snapshot_path(project: str, snapshot: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.snapshot_path
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.streaming_pull
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: streaming_pull
+ source:
+ id: streaming_pull
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 1455
+ summary: "Establishes a stream with the server, which sends messages down\nto the\
+ \ client. The client streams acknowledgements and ack\ndeadline modifications\
+ \ back to the server. The server will close\nthe stream and return the status\
+ \ on any error. The server may\nclose the stream with status `UNAVAILABLE` to\
+ \ reassign\nserver-side resources, in which case, the client should\nre-establish\
+ \ the stream. Flow control can be achieved by\nconfiguring the underlying RPC\
+ \ channel.\n\n```python\n# This snippet has been automatically generated and should\
+ \ be regarded as a\n# code template only.\n# It will require modifications to\
+ \ work:\n# - It may require correct/in-range values for request initialization.\n\
+ # - It may require specifying regional endpoints when creating the service\n#\
+ \ client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_streaming_pull():\n # Create a client\n\
+ \ client = pubsub_v1.SubscriberClient()\n\n # Initialize request argument(s)\n\
+ \ request = pubsub_v1.StreamingPullRequest(\n subscription=\"subscription_value\"\
+ ,\n stream_ack_deadline_seconds=2813,\n )\n\n # This method expects\
+ \ an iterator which contains\n # 'pubsub_v1.StreamingPullRequest' objects\n\
+ \ # Here we create a generator that yields a single `request` for\n # demonstrative\
+ \ purposes.\n requests = [request]\n\n def request_generator():\n \
+ \ for request in requests:\n yield request\n\n # Make the request\n\
+ \ stream = client.streaming_pull(requests=request_generator())\n\n # Handle\
+ \ the response\n for response in stream:\n print(response)\n```\n"
+ syntax:
+ content: "streaming_pull(\n requests: typing.Optional[\n typing.Iterator[google.cloud.pubsub_v1.types.StreamingPullRequest]\n\
+ \ ] = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> typing.Iterable[google.cloud.pubsub_v1.types.StreamingPullResponse]"
+ parameters:
+ - defaultValue: None
+ description: The request object iterator. Request for the StreamingPull
+ streaming RPC method. This request is used to establish the initial stream
+ as well as to stream acknowledgements and ack deadline modifications from
+ the client to the server.
+ id: requests
+ var_type: Iterator[google.pubsub_v1.types.StreamingPullRequest]
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response for the StreamingPull method. This response is used to
+ stream messages from the server to the client.
+ var_type: Iterable[google.pubsub_v1.types.StreamingPullResponse]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.streaming_pull
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.subscribe
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: subscribe
+ source:
+ id: subscribe
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
+ startLine: 149
+ summary: "Asynchronously start receiving messages on a given subscription.\n\nThis\
+ \ method starts a background thread to begin pulling messages from\na Pub/Sub\
+ \ subscription and scheduling them to be processed using the\nprovided `callback`.\n\
+ \nThe `callback` will be called with an individual\nxref_Message. It is the\n\
+ responsibility of the callback to either call `ack()` or `nack()`\non the message\
+ \ when it finished processing. If an exception occurs in\nthe callback during\
+ \ processing, the exception is logged and the message\nis `nack()` ed.\n\nThe\
+ \ `flow_control` argument can be used to control the rate of at\nwhich messages\
+ \ are pulled. The settings are relatively conservative by\ndefault to prevent\
+ \ \"message hoarding\" - a situation where the client\npulls a large number of\
+ \ messages but can not process them fast enough\nleading it to \"starve\" other\
+ \ clients of messages. Increasing these\nsettings may lead to faster throughput\
+ \ for messages that do not take\na long time to process.\n\nThe `use_legacy_flow_control`\
+ \ argument disables enforcing flow control\nsettings at the Cloud Pub/Sub server,\
+ \ and only the client side flow control\nwill be enforced.\n\nThis method starts\
+ \ the receiver in the background and returns a\n*Future* representing its execution.\
+ \ Waiting on the future (calling\n`result()`) will block forever or until a non-recoverable\
+ \ error\nis encountered (such as loss of network connectivity). Cancelling the\n\
+ future will signal the process to shutdown gracefully and exit.\n\n\nNote: \nproperties that may be surprising. Please take a look at\n\
+ https://cloud.google.com/pubsub/docs/pull#streamingpull for\nmore details on how\
+ \ streaming pull behaves compared to the\nsynchronous pull method.\n \n\
+ Example:\n\n```python\nfrom google.cloud import pubsub_v1\n\nsubscriber_client\
+ \ = pubsub_v1.SubscriberClient()\n\n# existing subscription\nsubscription = subscriber_client.subscription_path(\n\
+ \ 'my-project-id', 'my-subscription')\n\ndef callback(message):\n print(message)\n\
+ \ message.ack()\n\nfuture = subscriber_client.subscribe(\n subscription,\
+ \ callback)\n\ntry:\n future.result()\nexcept KeyboardInterrupt:\n future.cancel()\
+ \ # Trigger the shutdown.\n future.result() # Block until the shutdown is\
+ \ complete.\n```\n"
+ syntax:
+ content: "subscribe(\n subscription: str,\n callback: typing.Callable[[subscriber.message.Message],\
+ \ typing.Any],\n flow_control: typing.Union[\n google.cloud.pubsub_v1.types.FlowControl,\
+ \ typing.Sequence\n ] = (),\n scheduler: typing.Optional[subscriber.scheduler.ThreadScheduler]\
+ \ = None,\n use_legacy_flow_control: bool = False,\n await_callbacks_on_shutdown:\
+ \ bool = False,\n) -> google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture"
+ parameters:
+ - description: The name of the subscription. The subscription should have already
+ been created (for example, by using create_subscription).
+ id: subscription
+ var_type: str
+ - description: The callback function. This function receives the message as its
+ only argument and will be called from a different thread/ process depending
+ on the scheduling strategy.
+ id: callback
+ var_type: typing.Callable[[subscriber.message.Message], typing.Any]
+ - defaultValue: ()
+ description: The flow control settings. Use this to prevent situations where
+ you are inundated with too many messages at once.
+ id: flow_control
+ var_type: typing.Union[google.cloud.pubsub_v1.types.FlowControl ,
+ typing.Sequence]
+ - defaultValue: None
+ description: An optional *scheduler* to use when executing the callback. This
+ controls how callbacks are executed concurrently. This object must not be
+ shared across multiple SubscriberClient instances.
+ id: scheduler
+ var_type: typing.Optional[subscriber.scheduler.ThreadScheduler]
+ - defaultValue: 'False'
+ description: If set to True, flow control at the Cloud Pub/Sub
+ server is disabled, though client-side flow control is still enabled. If set
+ to False (default), both server-side and client-side flow control
+ are enabled.
+ id: use_legacy_flow_control
+ var_type: bool
+ - defaultValue: 'False'
+ description: If True, after canceling the returned future, the
+ latter's result() method will block until the background stream
+ and its helper threads have been terminated, and all currently executing message
+ callbacks are done processing. If False (default), the returned
+ future's result() method will not block after canceling the future.
+ The method will instead return immediately after the background stream and
+ its helper threads have been terminated, but some of the message callback
+ threads might still be running at that point.
+ id: await_callbacks_on_shutdown
+ var_type: bool
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.subscribe
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.subscription_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: subscription_path
+ source:
+ id: subscription_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 212
+ summary: 'Returns a fully-qualified subscription string.
+
+
+ '
+ syntax:
+ content: 'subscription_path(project: str, subscription: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.subscription_path
+- &id003
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.target
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: target
+ source:
+ id: target
+ path: null
+ startLine: null
+ summary: 'Return the target (where the API is).
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.target
+- *id003
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.test_iam_permissions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: test_iam_permissions
+ source:
+ id: test_iam_permissions
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 2574
+ summary: "Tests the specified IAM permissions against the IAM access control\n \
+ \ policy for a function.\n\nIf the function does not exist, this will return\
+ \ an empty set\nof permissions, not a NOT_FOUND error.\n"
+ syntax:
+ content: "test_iam_permissions(\n request: typing.Optional[\n google.iam.v1.iam_policy_pb2.TestIamPermissionsRequest\n\
+ \ ] = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.iam.v1.iam_policy_pb2.TestIamPermissionsResponse"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request message for TestIamPermissions
+ method.
+ id: request
+ var_type: .iam_policy_pb2.TestIamPermissionsRequest
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: Response message for TestIamPermissions method.
+ var_type: .iam_policy_pb2.TestIamPermissionsResponse
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.test_iam_permissions
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.topic_path
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: topic_path
+ source:
+ id: topic_path
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 231
+ summary: 'Returns a fully-qualified topic string.
+
+
+ '
+ syntax:
+ content: 'topic_path(project: str, topic: str) -> str'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.topic_path
+- &id004
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.transport
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: transport
+ source:
+ id: transport
+ path: null
+ startLine: null
+ summary: 'Returns the transport used by the client instance.
+
+ '
+ syntax:
+ returns:
+ - description: The transport used by the client instance.
+ var_type: SubscriberTransport
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.transport
+- *id004
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.update_snapshot
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: update_snapshot
+ source:
+ id: update_snapshot
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 2040
+ summary: "Updates an existing snapshot. Snapshots are used in\nSeek\noperations, which allow\nyou to manage message acknowledgments in bulk.\
+ \ That is,\nyou can set the acknowledgment state of messages in an\nexisting subscription\
+ \ to the state captured by a\nsnapshot.\n\n```python\n# This snippet has been\
+ \ automatically generated and should be regarded as a\n# code template only.\n\
+ # It will require modifications to work:\n# - It may require correct/in-range\
+ \ values for request initialization.\n# - It may require specifying regional endpoints\
+ \ when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_update_snapshot():\n # Create a\
+ \ client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n request = pubsub_v1.UpdateSnapshotRequest(\n )\n\n #\
+ \ Make the request\n response = client.update_snapshot(request=request)\n\n\
+ \ # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "update_snapshot(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.UpdateSnapshotRequest,\
+ \ dict]\n ] = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.cloud.pubsub_v1.types.Snapshot"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the UpdateSnapshot method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.UpdateSnapshotRequest, dict]
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A snapshot resource. Snapshots are used in [Seek](https://cloud.google.com/pubsub/docs/replay-overview)
+ operations, which allow you to manage message acknowledgments in bulk. That
+ is, you can set the acknowledgment state of messages in an existing subscription
+ to the state captured by a snapshot.
+ var_type: google.pubsub_v1.types.Snapshot
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.update_snapshot
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client.Client.update_subscription
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: update_subscription
+ source:
+ id: update_subscription
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/client.py
+ startLine: 779
+ summary: "Updates an existing subscription. Note that certain\nproperties of a subscription,\
+ \ such as its topic, are not\nmodifiable.\n\n```python\n# This snippet has been\
+ \ automatically generated and should be regarded as a\n# code template only.\n\
+ # It will require modifications to work:\n# - It may require correct/in-range\
+ \ values for request initialization.\n# - It may require specifying regional endpoints\
+ \ when creating the service\n# client as shown in:\n# https://googleapis.dev/python/google-api-core/latest/client_options.html\n\
+ from google import pubsub_v1\n\ndef sample_update_subscription():\n # Create\
+ \ a client\n client = pubsub_v1.SubscriberClient()\n\n # Initialize request\
+ \ argument(s)\n subscription = pubsub_v1.Subscription()\n subscription.name\
+ \ = \"name_value\"\n subscription.topic = \"topic_value\"\n\n request =\
+ \ pubsub_v1.UpdateSubscriptionRequest(\n subscription=subscription,\n \
+ \ )\n\n # Make the request\n response = client.update_subscription(request=request)\n\
+ \n # Handle the response\n print(response)\n```\n"
+ syntax:
+ content: "update_subscription(\n request: typing.Optional[\n typing.Union[google.cloud.pubsub_v1.types.UpdateSubscriptionRequest,\
+ \ dict]\n ] = None,\n *,\n retry: typing.Union[\n google.api_core.retry.Retry,\
+ \ google.api_core.gapic_v1.method._MethodDefault\n ] = _MethodDefault._DEFAULT_VALUE,\n\
+ \ timeout: typing.Optional[float] = None,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n) -> google.cloud.pubsub_v1.types.Subscription"
+ parameters:
+ - defaultValue: None
+ description: The request object. Request for the UpdateSubscription method.
+ id: request
+ var_type: Union[google.pubsub_v1.types.UpdateSubscriptionRequest, dict]
+ - description: Designation of what errors, if any, should be retried.
+ id: retry
+ var_type: google.api_core.retry.Retry
+ - description: The timeout for this request.
+ id: timeout
+ var_type: float
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ returns:
+ - description: A subscription resource.
+ var_type: google.pubsub_v1.types.Subscription
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.update_subscription
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client
+ isExternal: false
+ name: Client
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.acknowledge
+ isExternal: false
+ name: acknowledge
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.acknowledge
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.api
+ isExternal: false
+ name: api
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.api
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.close
+ isExternal: false
+ name: close
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.close
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.closed
+ isExternal: false
+ name: closed
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.closed
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_billing_account_path
+ isExternal: false
+ name: common_billing_account_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_billing_account_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_folder_path
+ isExternal: false
+ name: common_folder_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_folder_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_location_path
+ isExternal: false
+ name: common_location_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_location_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_organization_path
+ isExternal: false
+ name: common_organization_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_organization_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.common_project_path
+ isExternal: false
+ name: common_project_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.common_project_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.create_snapshot
+ isExternal: false
+ name: create_snapshot
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.create_snapshot
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.create_subscription
+ isExternal: false
+ name: create_subscription
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.create_subscription
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.delete_snapshot
+ isExternal: false
+ name: delete_snapshot
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.delete_snapshot
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.delete_subscription
+ isExternal: false
+ name: delete_subscription
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.delete_subscription
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_file
+ isExternal: false
+ name: from_service_account_file
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_file
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_info
+ isExternal: false
+ name: from_service_account_info
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_info
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_json
+ isExternal: false
+ name: from_service_account_json
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.from_service_account_json
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_iam_policy
+ isExternal: false
+ name: get_iam_policy
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_iam_policy
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_mtls_endpoint_and_cert_source
+ isExternal: false
+ name: get_mtls_endpoint_and_cert_source
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_mtls_endpoint_and_cert_source
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_snapshot
+ isExternal: false
+ name: get_snapshot
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_snapshot
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.get_subscription
+ isExternal: false
+ name: get_subscription
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.get_subscription
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.list_snapshots
+ isExternal: false
+ name: list_snapshots
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.list_snapshots
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.list_subscriptions
+ isExternal: false
+ name: list_subscriptions
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.list_subscriptions
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.modify_ack_deadline
+ isExternal: false
+ name: modify_ack_deadline
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.modify_ack_deadline
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.modify_push_config
+ isExternal: false
+ name: modify_push_config
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.modify_push_config
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_billing_account_path
+ isExternal: false
+ name: parse_common_billing_account_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_billing_account_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_folder_path
+ isExternal: false
+ name: parse_common_folder_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_folder_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_location_path
+ isExternal: false
+ name: parse_common_location_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_location_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_organization_path
+ isExternal: false
+ name: parse_common_organization_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_organization_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_project_path
+ isExternal: false
+ name: parse_common_project_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_common_project_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_snapshot_path
+ isExternal: false
+ name: parse_snapshot_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_snapshot_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_subscription_path
+ isExternal: false
+ name: parse_subscription_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_subscription_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.parse_topic_path
+ isExternal: false
+ name: parse_topic_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.parse_topic_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.pull
+ isExternal: false
+ name: pull
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.pull
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.seek
+ isExternal: false
+ name: seek
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.seek
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.set_iam_policy
+ isExternal: false
+ name: set_iam_policy
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.set_iam_policy
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.snapshot_path
+ isExternal: false
+ name: snapshot_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.snapshot_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.streaming_pull
+ isExternal: false
+ name: streaming_pull
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.streaming_pull
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.subscribe
+ isExternal: false
+ name: subscribe
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.subscribe
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.subscription_path
+ isExternal: false
+ name: subscription_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.subscription_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.target
+ isExternal: false
+ name: target
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.target
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.test_iam_permissions
+ isExternal: false
+ name: test_iam_permissions
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.test_iam_permissions
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.topic_path
+ isExternal: false
+ name: topic_path
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.topic_path
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.transport
+ isExternal: false
+ name: transport
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.transport
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.update_snapshot
+ isExternal: false
+ name: update_snapshot
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.update_snapshot
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client.update_subscription
+ isExternal: false
+ name: update_subscription
+ parent: google.cloud.pubsub_v1.subscriber.client.Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client.update_subscription
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.client.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.client.yml
new file mode 100644
index 000000000000..d21ef5a12e7d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.client.yml
@@ -0,0 +1,24 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.subscriber.client.Client
+ fullName: google.cloud.pubsub_v1.subscriber.client
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.client
+ name: subscriber.client
+ source:
+ id: client
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/client.py
+ startLine: 0
+ summary: API documentation for `pubsub_v1.subscriber.client` module.
+ syntax: {}
+ type: module
+ uid: google.cloud.pubsub_v1.subscriber.client
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.client.Client
+ isExternal: false
+ name: Client
+ parent: google.cloud.pubsub_v1.subscriber.client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.Future.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.Future.yml
new file mode 100644
index 000000000000..3b568c146392
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.Future.yml
@@ -0,0 +1,374 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.subscriber.futures.Future
+ - google.cloud.pubsub_v1.subscriber.futures.Future.add_done_callback
+ - google.cloud.pubsub_v1.subscriber.futures.Future.cancel
+ - google.cloud.pubsub_v1.subscriber.futures.Future.cancelled
+ - google.cloud.pubsub_v1.subscriber.futures.Future.done
+ - google.cloud.pubsub_v1.subscriber.futures.Future.exception
+ - google.cloud.pubsub_v1.subscriber.futures.Future.result
+ - google.cloud.pubsub_v1.subscriber.futures.Future.running
+ - google.cloud.pubsub_v1.subscriber.futures.Future.set_exception
+ - google.cloud.pubsub_v1.subscriber.futures.Future.set_result
+ - google.cloud.pubsub_v1.subscriber.futures.Future.set_running_or_notify_cancel
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: Future
+ source:
+ id: Future
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 86
+ summary: 'This future object is for subscribe-side calls.
+
+
+ Calling `result` will resolve the future by returning the message
+
+ ID, unless an error occurs.
+
+
+ '
+ syntax:
+ content: Future()
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: Future
+ source:
+ id: Future
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 86
+ summary: 'Initializes the future. Should not be called by clients.
+
+
+ '
+ syntax:
+ content: Future()
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.add_done_callback
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: add_done_callback
+ source:
+ id: add_done_callback
+ path: concurrent/futures/_base.py
+ startLine: 410
+ summary: 'Attaches a callable that will be called when the future finishes.
+
+ '
+ syntax:
+ content: add_done_callback(fn)
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.add_done_callback
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.cancel
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: cancel
+ source:
+ id: cancel
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 93
+ summary: 'Actions in Pub/Sub generally may not be canceled.
+
+
+ This method always returns `False`.
+
+
+ '
+ syntax:
+ content: cancel() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.cancel
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.cancelled
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: cancelled
+ source:
+ id: cancelled
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 100
+ summary: 'Actions in Pub/Sub generally may not be canceled.
+
+
+ This method always returns `False`.
+
+
+ '
+ syntax:
+ content: cancelled() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.cancelled
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.done
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: done
+ source:
+ id: done
+ path: concurrent/futures/_base.py
+ startLine: 395
+ summary: 'Return True if the future was cancelled or finished executing.
+
+
+ '
+ syntax:
+ content: done()
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.done
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.exception
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: exception
+ source:
+ id: exception
+ path: concurrent/futures/_base.py
+ startLine: 465
+ summary: 'Return the exception raised by the call that the future represents.
+
+ '
+ syntax:
+ content: exception(timeout=None)
+ exceptions:
+ - description: If the future was cancelled.
+ var_type: CancelledError
+ - description: If the future didn't finish executing before the given timeout.
+ var_type: TimeoutError
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.exception
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.result
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: result
+ source:
+ id: result
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 107
+ summary: 'Return a success code or raise an exception.
+
+
+ This blocks until the operation completes successfully and
+
+ returns the error code unless an exception is raised.
+
+ '
+ syntax:
+ content: "result(\n timeout: typing.Optional[typing.Union[int, float]] = None\n\
+ ) -> google.cloud.pubsub_v1.subscriber.exceptions.AcknowledgeStatus"
+ exceptions:
+ - description: If the request times out.
+ var_type: concurrent.futures.TimeoutError
+ - description: If the operation did not succeed for another reason.
+ var_type: AcknowledgeError
+ parameters:
+ - defaultValue: None
+ description: The number of seconds before this call times out and raises TimeoutError.
+ id: timeout
+ var_type: typing.Union[int, float]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.result
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.running
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: running
+ source:
+ id: running
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 33
+ summary: 'Return `True` if the associated Pub/Sub action has not yet completed.
+
+
+ '
+ syntax:
+ content: running() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.running
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.set_exception
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: set_exception
+ source:
+ id: set_exception
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 50
+ summary: 'Set the result of the future as being the given exception.
+
+
+ Do not use this method, it should only be used internally by the library and its
+
+ unit tests.
+
+
+ '
+ syntax:
+ content: 'set_exception(exception: typing.Optional[BaseException])'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.set_exception
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.set_result
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: set_result
+ source:
+ id: set_result
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 42
+ summary: 'Set the return value of work associated with the future.
+
+
+ Do not use this method, it should only be used internally by the library and its
+
+ unit tests.
+
+
+ '
+ syntax:
+ content: 'set_result(result: typing.Any)'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.set_result
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.Future
+ fullName: google.cloud.pubsub_v1.subscriber.futures.Future.set_running_or_notify_cancel
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: set_running_or_notify_cancel
+ source:
+ id: set_running_or_notify_cancel
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 37
+ summary: 'Mark the future as running or process any cancel notifications.
+
+
+ Should only be used by Executor implementations and unit tests.
+
+
+ If the future has been cancelled (cancel() was called and returned
+
+ True) then any threads waiting on the future completing (though calls
+
+ to as_completed() or wait()) are notified and False is returned.
+
+
+ If the future was not cancelled then it is put in the running state
+
+ (future calls to running() will return True) and True is returned.
+
+
+ This method should be called by Executor implementations before
+
+ executing the work associated with this future. If this method returns
+
+ False then the work should not be executed.
+
+ '
+ syntax:
+ content: set_running_or_notify_cancel() -> typing.NoReturn
+ exceptions:
+ - description: if this method was already called or if set_result() or set_exception()
+ was called.
+ var_type: RuntimeError
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.set_running_or_notify_cancel
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future
+ isExternal: false
+ name: Future
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.add_done_callback
+ isExternal: false
+ name: add_done_callback
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.add_done_callback
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.cancel
+ isExternal: false
+ name: cancel
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.cancel
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.cancelled
+ isExternal: false
+ name: cancelled
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.cancelled
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.done
+ isExternal: false
+ name: done
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.done
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.exception
+ isExternal: false
+ name: exception
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.exception
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.result
+ isExternal: false
+ name: result
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.result
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.running
+ isExternal: false
+ name: running
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.running
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.set_exception
+ isExternal: false
+ name: set_exception
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.set_exception
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.set_result
+ isExternal: false
+ name: set_result
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.set_result
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future.set_running_or_notify_cancel
+ isExternal: false
+ name: set_running_or_notify_cancel
+ parent: google.cloud.pubsub_v1.subscriber.futures.Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future.set_running_or_notify_cancel
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.yml
new file mode 100644
index 000000000000..bc6b2cd1afaa
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.yml
@@ -0,0 +1,365 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.add_done_callback
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancel
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancelled
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.done
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.exception
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.result
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.running
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_exception
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_result
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_running_or_notify_cancel
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: StreamingPullFuture
+ source:
+ id: StreamingPullFuture
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 30
+ summary: 'Represents a process that asynchronously performs streaming pull and
+
+ schedules messages to be processed.
+
+
+ This future is resolved when the process is stopped (via `cancel`) or
+
+ if it encounters an unrecoverable error. Calling `.result()` will cause
+
+ the calling thread to block indefinitely.
+
+
+ '
+ syntax:
+ content: 'StreamingPullFuture(manager: StreamingPullManager)'
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: StreamingPullFuture
+ source:
+ id: StreamingPullFuture
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 30
+ summary: 'Initializes the future. Should not be called by clients.
+
+
+ '
+ syntax:
+ content: 'StreamingPullFuture(manager: StreamingPullManager)'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.add_done_callback
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: add_done_callback
+ source:
+ id: add_done_callback
+ path: concurrent/futures/_base.py
+ startLine: 410
+ summary: 'Attaches a callable that will be called when the future finishes.
+
+ '
+ syntax:
+ content: add_done_callback(fn)
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.add_done_callback
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancel
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: cancel
+ source:
+ id: cancel
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 56
+ summary: "Stops pulling messages and shutdowns the background thread consuming\n\
+ messages.\n\nThe method always returns `True`, as the shutdown is always initiated.\n\
+ However, if the background stream is already being shut down or the shutdown\n\
+ has completed, this method is a no-op.\n\n.. versionchanged:: 2.4.1\n The method\
+ \ does not block anymore, it just triggers the shutdown and returns\n immediately.\
+ \ To block until the background stream is terminated, call\n `result()` after\
+ \ cancelling the future.\n\n.. versionchanged:: 2.10.0\n The method always returns\
+ \ `True` instead of `None`.\n\n"
+ syntax:
+ content: cancel() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancel
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancelled
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: cancelled
+ source:
+ id: cancelled
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 78
+ summary: ''
+ syntax:
+ content: cancelled() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancelled
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.done
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: done
+ source:
+ id: done
+ path: concurrent/futures/_base.py
+ startLine: 395
+ summary: 'Return True if the future was cancelled or finished executing.
+
+
+ '
+ syntax:
+ content: done()
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.done
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.exception
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: exception
+ source:
+ id: exception
+ path: concurrent/futures/_base.py
+ startLine: 465
+ summary: 'Return the exception raised by the call that the future represents.
+
+ '
+ syntax:
+ content: exception(timeout=None)
+ exceptions:
+ - description: If the future was cancelled.
+ var_type: CancelledError
+ - description: If the future didn't finish executing before the given timeout.
+ var_type: TimeoutError
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.exception
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.result
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: result
+ source:
+ id: result
+ path: concurrent/futures/_base.py
+ startLine: 430
+ summary: 'Return the result of the call that the future represents.
+
+ '
+ syntax:
+ content: result(timeout=None)
+ exceptions:
+ - description: If the future was cancelled.
+ var_type: CancelledError
+ - description: If the future didn't finish executing before the given timeout.
+ var_type: TimeoutError
+ - description: If the call raised then that exception will be raised.
+ var_type: Exception
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.result
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.running
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: running
+ source:
+ id: running
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 33
+ summary: 'Return `True` if the associated Pub/Sub action has not yet completed.
+
+
+ '
+ syntax:
+ content: running() -> bool
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.running
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_exception
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: set_exception
+ source:
+ id: set_exception
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 50
+ summary: 'Set the result of the future as being the given exception.
+
+
+ Do not use this method, it should only be used internally by the library and its
+
+ unit tests.
+
+
+ '
+ syntax:
+ content: 'set_exception(exception: typing.Optional[BaseException])'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_exception
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_result
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: set_result
+ source:
+ id: set_result
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 42
+ summary: 'Set the return value of work associated with the future.
+
+
+ Do not use this method, it should only be used internally by the library and its
+
+ unit tests.
+
+
+ '
+ syntax:
+ content: 'set_result(result: typing.Any)'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_result
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_running_or_notify_cancel
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: set_running_or_notify_cancel
+ source:
+ id: set_running_or_notify_cancel
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/futures.py
+ startLine: 37
+ summary: 'Mark the future as running or process any cancel notifications.
+
+
+ Should only be used by Executor implementations and unit tests.
+
+
+ If the future has been cancelled (cancel() was called and returned
+
+ True) then any threads waiting on the future completing (though calls
+
+ to as_completed() or wait()) are notified and False is returned.
+
+
+ If the future was not cancelled then it is put in the running state
+
+ (future calls to running() will return True) and True is returned.
+
+
+ This method should be called by Executor implementations before
+
+ executing the work associated with this future. If this method returns
+
+ False then the work should not be executed.
+
+ '
+ syntax:
+ content: set_running_or_notify_cancel() -> typing.NoReturn
+ exceptions:
+ - description: if this method was already called or if set_result() or set_exception()
+ was called.
+ var_type: RuntimeError
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_running_or_notify_cancel
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ isExternal: false
+ name: StreamingPullFuture
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.add_done_callback
+ isExternal: false
+ name: add_done_callback
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.add_done_callback
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancel
+ isExternal: false
+ name: cancel
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancel
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancelled
+ isExternal: false
+ name: cancelled
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.cancelled
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.done
+ isExternal: false
+ name: done
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.done
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.exception
+ isExternal: false
+ name: exception
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.exception
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.result
+ isExternal: false
+ name: result
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.result
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.running
+ isExternal: false
+ name: running
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.running
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_exception
+ isExternal: false
+ name: set_exception
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_exception
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_result
+ isExternal: false
+ name: set_result
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_result
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_running_or_notify_cancel
+ isExternal: false
+ name: set_running_or_notify_cancel
+ parent: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture.set_running_or_notify_cancel
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.yml
new file mode 100644
index 000000000000..0076cfacb152
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.futures.yml
@@ -0,0 +1,30 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.subscriber.futures.Future
+ - google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ fullName: google.cloud.pubsub_v1.subscriber.futures
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.futures
+ name: subscriber.futures
+ source:
+ id: futures
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/futures.py
+ startLine: 0
+ summary: API documentation for `pubsub_v1.subscriber.futures` module.
+ syntax: {}
+ type: module
+ uid: google.cloud.pubsub_v1.subscriber.futures
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.futures.Future
+ isExternal: false
+ name: Future
+ parent: google.cloud.pubsub_v1.subscriber.futures
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future
+- fullName: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ isExternal: false
+ name: StreamingPullFuture
+ parent: google.cloud.pubsub_v1.subscriber.futures
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.message.Message.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.message.Message.yml
new file mode 100644
index 000000000000..7bf66253610f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.message.Message.yml
@@ -0,0 +1,675 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.subscriber.message.Message
+ - google.cloud.pubsub_v1.subscriber.message.Message.ack
+ - google.cloud.pubsub_v1.subscriber.message.Message.ack_id
+ - google.cloud.pubsub_v1.subscriber.message.Message.ack_with_response
+ - google.cloud.pubsub_v1.subscriber.message.Message.attributes
+ - google.cloud.pubsub_v1.subscriber.message.Message.data
+ - google.cloud.pubsub_v1.subscriber.message.Message.delivery_attempt
+ - google.cloud.pubsub_v1.subscriber.message.Message.drop
+ - google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline
+ - google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline_with_response
+ - google.cloud.pubsub_v1.subscriber.message.Message.nack
+ - google.cloud.pubsub_v1.subscriber.message.Message.nack_with_response
+ - google.cloud.pubsub_v1.subscriber.message.Message.ordering_key
+ - google.cloud.pubsub_v1.subscriber.message.Message.publish_time
+ - google.cloud.pubsub_v1.subscriber.message.Message.size
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: Message
+ source:
+ id: Message
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 67
+ summary: "A representation of a single Pub/Sub message.\n\nThe common way to interact\
+ \ with\n`.pubsub_v1.subscriber.message.Message` objects is to receive\nthem in\
+ \ callbacks on subscriptions; most users should never have a need\nto instantiate\
+ \ them by hand. (The exception to this is if you are\nimplementing a custom subclass\
+ \ to\n`.pubsub_v1.subscriber._consumer.Consumer`.)\n\n The data in the message.\
+ \ Note that this will be a `bytes`,\n not a text string.\n\n The time that\
+ \ this message was originally published.\n\n"
+ syntax:
+ content: 'Message(message: types.PubsubMessage._meta._pb, ack_id: str, delivery_attempt:
+ int, request_queue: queue.Queue, exactly_once_delivery_enabled_func: typing.Callable[[],
+ bool] = >)'
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.subscriber.message.Message
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: Message
+ source:
+ id: Message
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 67
+ summary: 'Construct the Message.
+
+
+
+
+ Note:
+
+ This class should not be constructed directly; it is the
+
+ responsibility of `BasePolicy` subclasses to do so.
+
+ '
+ syntax:
+ content: 'Message(message: types.PubsubMessage._meta._pb, ack_id: str, delivery_attempt:
+ int, request_queue: queue.Queue, exactly_once_delivery_enabled_func: typing.Callable[[],
+ bool] = >)'
+ parameters:
+ - description: The ack_id received from Pub/Sub.
+ id: ack_id
+ var_type: str
+ - description: The delivery attempt counter received from Pub/Sub if a DeadLetterPolicy
+ is set on the subscription, and zero otherwise.
+ id: delivery_attempt
+ var_type: int
+ - description: A Callable that returns whether exactly-once delivery is currently-enabled.
+ Defaults to a lambda that always returns False.
+ id: exactly_once_delivery_enabled_func
+ var_type: typing.Callable[[], bool]
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.ack
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: ack
+ source:
+ id: ack
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 234
+ summary: 'Acknowledge the given message.
+
+
+ Acknowledging a message in Pub/Sub means that you are done
+
+ with it, and it will not be delivered to this subscription again.
+
+ You should avoid acknowledging messages until you have
+
+ *finished* processing them, so that in the event of a failure,
+
+ you receive the message again.
+
+
+
+
+ Warning:
+
+ Acks in Pub/Sub are best effort. You should always
+
+ ensure that your processing code is idempotent, as you may
+
+ receive any given message more than once. If you need strong
+
+ guarantees about acks and re-deliveres, enable exactly-once
+
+ delivery on your subscription and use the `ack_with_response`
+
+ method instead. Exactly once delivery is a preview feature.
+
+ For more details, see:
+
+ https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ '
+ syntax:
+ content: ack() -> None
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ack
+- &id001
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.ack_id
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: ack_id
+ source:
+ id: ack_id
+ path: null
+ startLine: null
+ summary: 'the ID used to ack the message.
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ack_id
+- *id001
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.ack_with_response
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: ack_with_response
+ source:
+ id: ack_with_response
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 265
+ summary: 'Acknowledge the given message.
+
+
+ Acknowledging a message in Pub/Sub means that you are done
+
+ with it, and it will not be delivered to this subscription again.
+
+ You should avoid acknowledging messages until you have
+
+ *finished* processing them, so that in the event of a failure,
+
+ you receive the message again.
+
+
+ If exactly-once delivery is NOT enabled on the subscription, the
+
+ future returns immediately with an AcknowledgeStatus.SUCCESS.
+
+ Since acks in Cloud Pub/Sub are best effort when exactly-once
+
+ delivery is disabled, the message may be re-delivered. Because
+
+ re-deliveries are possible, you should ensure that your processing
+
+ code is idempotent, as you may receive any given message more than
+
+ once.
+
+
+ If exactly-once delivery is enabled on the subscription, the
+
+ future returned by this method tracks the state of acknowledgement
+
+ operation. If the future completes successfully, the message is
+
+ guaranteed NOT to be re-delivered. Otherwise, the future will
+
+ contain an exception with more details about the failure and the
+
+ message may be re-delivered.
+
+
+ Exactly once delivery is a preview feature. For more details,
+
+ see https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ '
+ syntax:
+ content: ack_with_response() -> google.cloud.pubsub_v1.subscriber.futures.Future
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ack_with_response
+- &id002
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.attributes
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: attributes
+ source:
+ id: attributes
+ path: null
+ startLine: null
+ summary: 'Return the attributes of the underlying Pub/Sub Message.
+
+
+
+
+ Warning:
+
+ A `ScalarMap` behaves slightly differently than a
+
+ `dict`. For a Pub / Sub message this is a `string->string` map.
+
+ When trying to access a value via `map[''key'']`, if the key is
+
+ not in the map, then the default value for the string type will
+
+ be returned, which is an empty string. It may be more intuitive
+
+ to just cast the map to a `dict` or to one use `map.get`.
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.attributes
+- *id002
+- &id003
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.data
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: data
+ source:
+ id: data
+ path: null
+ startLine: null
+ summary: 'Return the data for the underlying Pub/Sub Message.
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.data
+- *id003
+- &id004
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.delivery_attempt
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: delivery_attempt
+ source:
+ id: delivery_attempt
+ path: null
+ startLine: null
+ summary: 'The delivery attempt counter is 1 + (the sum of number of NACKs
+
+ and number of ack_deadline exceeds) for this message. It is set to None
+
+ if a DeadLetterPolicy is not set on the subscription.
+
+
+ A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
+
+ exceeds event is whenever a message is not acknowledged within
+
+ ack_deadline. Note that ack_deadline is initially
+
+ Subscription.ackDeadlineSeconds, but may get extended automatically by
+
+ the client library.
+
+
+ The first delivery of a given message will have this value as 1. The value
+
+ is calculated at best effort and is approximate.
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.delivery_attempt
+- *id004
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.drop
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: drop
+ source:
+ id: drop
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 322
+ summary: 'Release the message from lease management.
+
+
+ This informs the policy to no longer hold on to the lease for this
+
+ message. Pub/Sub will re-deliver the message if it is not acknowledged
+
+ before the existing lease expires.
+
+
+
+
+ Warning:
+
+ For most use cases, the only reason to drop a message from
+
+ lease management is on `ack` or `nack`; this library
+
+ automatically drop()s the message on `ack` or `nack`. You probably
+
+ do not want to call this method directly.
+
+ '
+ syntax:
+ content: drop() -> None
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.drop
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: modify_ack_deadline
+ source:
+ id: modify_ack_deadline
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 341
+ summary: 'Resets the deadline for acknowledgement.
+
+
+ New deadline will be the given value of seconds from now.
+
+
+ The default implementation handles automatically modacking received messages for
+ you;
+
+ you should not need to manually deal with setting ack deadlines. The exception
+ case is
+
+ if you are implementing your own custom subclass of
+
+ `.pubsub_v1.subcriber._consumer.Consumer`.
+
+ '
+ syntax:
+ content: 'modify_ack_deadline(seconds: int) -> None'
+ parameters:
+ - description: The number of seconds to set the lease deadline to. This should
+ be between 0 and 600. Due to network latency, values below 10 are advised
+ against.
+ id: seconds
+ var_type: int
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline_with_response
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: modify_ack_deadline_with_response
+ source:
+ id: modify_ack_deadline_with_response
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 361
+ summary: 'Resets the deadline for acknowledgement and returns the response
+
+ status via a future.
+
+
+ New deadline will be the given value of seconds from now.
+
+
+ The default implementation handles automatically modacking received messages for
+ you;
+
+ you should not need to manually deal with setting ack deadlines. The exception
+ case is
+
+ if you are implementing your own custom subclass of
+
+ `.pubsub_v1.subcriber._consumer.Consumer`.
+
+
+ If exactly-once delivery is NOT enabled on the subscription, the
+
+ future returns immediately with an AcknowledgeStatus.SUCCESS.
+
+ Since modify-ack-deadline operations in Cloud Pub/Sub are best effort
+
+ when exactly-once delivery is disabled, the message may be re-delivered
+
+ within the set deadline.
+
+
+ If exactly-once delivery is enabled on the subscription, the
+
+ future returned by this method tracks the state of the
+
+ modify-ack-deadline operation. If the future completes successfully,
+
+ the message is guaranteed NOT to be re-delivered within the new deadline.
+
+ Otherwise, the future will contain an exception with more details about
+
+ the failure and the message will be redelivered according to its
+
+ currently-set ack deadline.
+
+
+ Exactly once delivery is a preview feature. For more details,
+
+ see https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ '
+ syntax:
+ content: "modify_ack_deadline_with_response(\n seconds: int,\n) -> google.cloud.pubsub_v1.subscriber.futures.Future"
+ parameters:
+ - description: The number of seconds to set the lease deadline to. This should
+ be between 0 and 600. Due to network latency, values below 10 are advised
+ against.
+ id: seconds
+ var_type: int
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline_with_response
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.nack
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: nack
+ source:
+ id: nack
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 422
+ summary: 'Decline to acknowledge the given message.
+
+
+ This will cause the message to be re-delivered to subscribers. Re-deliveries
+
+ may take place immediately or after a delay, and may arrive at this subscriber
+
+ or another.
+
+
+ '
+ syntax:
+ content: nack() -> None
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.nack
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.nack_with_response
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: nack_with_response
+ source:
+ id: nack_with_response
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/message.py
+ startLine: 438
+ summary: 'Decline to acknowledge the given message, returning the response status
+ via
+
+ a future.
+
+
+ This will cause the message to be re-delivered to subscribers. Re-deliveries
+
+ may take place immediately or after a delay, and may arrive at this subscriber
+
+ or another.
+
+
+ If exactly-once delivery is NOT enabled on the subscription, the
+
+ future returns immediately with an AcknowledgeStatus.SUCCESS.
+
+
+ If exactly-once delivery is enabled on the subscription, the
+
+ future returned by this method tracks the state of the
+
+ nack operation. If the future completes successfully,
+
+ the future''s result will be an AcknowledgeStatus.SUCCESS.
+
+ Otherwise, the future will contain an exception with more details about
+
+ the failure.
+
+
+ Exactly once delivery is a preview feature. For more details,
+
+ see https://cloud.google.com/pubsub/docs/exactly-once-delivery."
+
+ '
+ syntax:
+ content: nack_with_response() -> google.cloud.pubsub_v1.subscriber.futures.Future
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.nack_with_response
+- &id005
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.ordering_key
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: ordering_key
+ source:
+ id: ordering_key
+ path: null
+ startLine: null
+ summary: 'The ordering key used to publish the message.
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ordering_key
+- *id005
+- &id006
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.publish_time
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: publish_time
+ source:
+ id: publish_time
+ path: null
+ startLine: null
+ summary: 'Return the time that the message was originally published.
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.publish_time
+- *id006
+- &id007
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.message.Message
+ fullName: google.cloud.pubsub_v1.subscriber.message.Message.size
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.message
+ name: size
+ source:
+ id: size
+ path: null
+ startLine: null
+ summary: 'Return the size of the underlying message, in bytes.
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.size
+- *id007
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message
+ isExternal: false
+ name: Message
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.ack
+ isExternal: false
+ name: ack
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ack
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.ack_id
+ isExternal: false
+ name: ack_id
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ack_id
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.ack_with_response
+ isExternal: false
+ name: ack_with_response
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ack_with_response
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.attributes
+ isExternal: false
+ name: attributes
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.attributes
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.data
+ isExternal: false
+ name: data
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.data
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.delivery_attempt
+ isExternal: false
+ name: delivery_attempt
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.delivery_attempt
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.drop
+ isExternal: false
+ name: drop
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.drop
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline
+ isExternal: false
+ name: modify_ack_deadline
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline_with_response
+ isExternal: false
+ name: modify_ack_deadline_with_response
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.modify_ack_deadline_with_response
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.nack
+ isExternal: false
+ name: nack
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.nack
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.nack_with_response
+ isExternal: false
+ name: nack_with_response
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.nack_with_response
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.ordering_key
+ isExternal: false
+ name: ordering_key
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.ordering_key
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.publish_time
+ isExternal: false
+ name: publish_time
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.publish_time
+- fullName: google.cloud.pubsub_v1.subscriber.message.Message.size
+ isExternal: false
+ name: size
+ parent: google.cloud.pubsub_v1.subscriber.message.Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message.size
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.yml
new file mode 100644
index 000000000000..1e9d6105df09
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.yml
@@ -0,0 +1,117 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.queue
+ - google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.schedule
+ - google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.shutdown
+ class: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: Scheduler
+ source:
+ id: Scheduler
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
+ startLine: 32
+ summary: 'Abstract base class for schedulers.
+
+
+ Schedulers are used to schedule callbacks asynchronously.
+
+
+ '
+ syntax:
+ content: Scheduler()
+ type: class
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+- &id001
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.queue
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: queue
+ source:
+ id: queue
+ path: null
+ startLine: null
+ summary: 'Queue: A concurrency-safe queue specific to the underlying
+
+ concurrency implementation.
+
+
+ This queue is used to send messages *back* to the scheduling actor.
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.queue
+- *id001
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.schedule
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: schedule
+ source:
+ id: schedule
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
+ startLine: 48
+ summary: 'Schedule the callback to be called asynchronously.
+
+ '
+ syntax:
+ content: 'schedule(callback: typing.Callable, *args, **kwargs) -> None'
+ parameters:
+ - description: The function to call.
+ id: callback
+ var_type: Callable
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.schedule
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.shutdown
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: shutdown
+ source:
+ id: shutdown
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
+ startLine: 62
+ summary: 'Shuts down the scheduler and immediately end all pending callbacks.
+
+ '
+ syntax:
+ content: "shutdown(\n await_msg_callbacks: bool = False,\n) -> typing.List[pubsub_v1.subscriber.message.Message]"
+ parameters:
+ - defaultValue: 'False'
+ description: If True, the method will block until all currently
+ executing callbacks are done processing. If False (default),
+ the method will not wait for the currently running callbacks to complete.
+ id: await_msg_callbacks
+ var_type: bool
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.shutdown
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.queue
+ isExternal: false
+ name: queue
+ parent: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.queue
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.schedule
+ isExternal: false
+ name: schedule
+ parent: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.schedule
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.shutdown
+ isExternal: false
+ name: shutdown
+ parent: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler.shutdown
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.yml
new file mode 100644
index 000000000000..c308281af9ea
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.yml
@@ -0,0 +1,116 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.queue
+ - google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.schedule
+ - google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.shutdown
+ class: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: ThreadScheduler
+ source:
+ id: ThreadScheduler
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
+ startLine: 89
+ summary: "A thread pool-based scheduler. It must not be shared across\n SubscriberClients.\n\
+ \nThis scheduler is useful in typical I/O-bound message processing.\n"
+ syntax:
+ content: "ThreadScheduler(\n executor: typing.Optional[concurrent.futures.thread.ThreadPoolExecutor]\
+ \ = None,\n)"
+ parameters:
+ - defaultValue: None
+ description: An optional executor to use. If not specified, a default one will
+ be created.
+ id: executor
+ var_type: typing.Optional[concurrent.futures.thread.ThreadPoolExecutor]
+ type: class
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+- &id001
+ attributes: []
+ class: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.queue
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: queue
+ source:
+ id: queue
+ path: null
+ startLine: null
+ summary: 'Queue: A thread-safe queue used for communication between callbacks
+
+ and the scheduling thread.
+
+
+ '
+ syntax: {}
+ type: property
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.queue
+- *id001
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.schedule
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: schedule
+ source:
+ id: schedule
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
+ startLine: 116
+ summary: 'Schedule the callback to be called asynchronously in a thread pool.
+
+ '
+ syntax:
+ content: 'schedule(callback: typing.Callable, *args, **kwargs) -> None'
+ parameters:
+ - description: The function to call.
+ id: callback
+ var_type: Callable
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.schedule
+- attributes: []
+ class: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.shutdown
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: shutdown
+ source:
+ id: shutdown
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
+ startLine: 136
+ summary: 'Shut down the scheduler and immediately end all pending callbacks.
+
+ '
+ syntax:
+ content: "shutdown(\n await_msg_callbacks: bool = False,\n) -> typing.List[pubsub_v1.subscriber.message.Message]"
+ parameters:
+ - defaultValue: 'False'
+ description: If True, the method will block until all currently
+ executing executor threads are done processing. If False (default),
+ the method will not wait for the currently running threads to complete.
+ id: await_msg_callbacks
+ var_type: bool
+ type: method
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.shutdown
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.queue
+ isExternal: false
+ name: queue
+ parent: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.queue
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.schedule
+ isExternal: false
+ name: schedule
+ parent: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.schedule
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.shutdown
+ isExternal: false
+ name: shutdown
+ parent: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler.shutdown
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.yml
new file mode 100644
index 000000000000..98de6f8a0bcb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.subscriber.scheduler.yml
@@ -0,0 +1,39 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ - google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ fullName: google.cloud.pubsub_v1.subscriber.scheduler
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.subscriber.scheduler
+ name: scheduler
+ source:
+ id: scheduler
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/subscriber/scheduler.py
+ startLine: 0
+ summary: 'Schedulers provide means to *schedule* callbacks asynchronously.
+
+
+ These are used by the subscriber to call the user-provided callback to process
+
+ each message.
+
+
+ '
+ syntax: {}
+ type: module
+ uid: google.cloud.pubsub_v1.subscriber.scheduler
+references:
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ isExternal: false
+ name: Scheduler
+ parent: google.cloud.pubsub_v1.subscriber.scheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+- fullName: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ isExternal: false
+ name: ThreadScheduler
+ parent: google.cloud.pubsub_v1.subscriber.scheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AcknowledgeRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AcknowledgeRequest.yml
new file mode 100644
index 000000000000..2c3a5d15836f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AcknowledgeRequest.yml
@@ -0,0 +1,33 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The subscription whose message is being\n acknowledged.\
+ \ Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ - description: "Required. The acknowledgment ID for the messages being\n acknowledged\
+ \ that was returned by the Pub/Sub system in the\n Pull response.\
+ \ Must not be empty."
+ id: ack_ids
+ var_type: Sequence[str]
+ children: []
+ class: google.cloud.pubsub_v1.types.AcknowledgeRequest
+ fullName: google.cloud.pubsub_v1.types.AcknowledgeRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: AcknowledgeRequest
+ source:
+ id: AcknowledgeRequest
+ path: null
+ startLine: null
+ summary: 'Request for the Acknowledge method.
+
+ '
+ syntax:
+ content: AcknowledgeRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.AcknowledgeRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditConfig.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditConfig.yml
new file mode 100644
index 000000000000..4cf95c3bb79d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditConfig.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.AuditConfig
+ fullName: google.cloud.pubsub_v1.types.AuditConfig
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: AuditConfig
+ source:
+ id: AuditConfig
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.AuditConfig` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.AuditConfig
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditConfigDelta.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditConfigDelta.yml
new file mode 100644
index 000000000000..58cf719f201f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditConfigDelta.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.AuditConfigDelta
+ fullName: google.cloud.pubsub_v1.types.AuditConfigDelta
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: AuditConfigDelta
+ source:
+ id: AuditConfigDelta
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.AuditConfigDelta` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.AuditConfigDelta
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditData.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditData.yml
new file mode 100644
index 000000000000..179230f60326
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditData.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.AuditData
+ fullName: google.cloud.pubsub_v1.types.AuditData
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: AuditData
+ source:
+ id: AuditData
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.AuditData` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.AuditData
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditLogConfig.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditLogConfig.yml
new file mode 100644
index 000000000000..1a5ec3697d4c
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.AuditLogConfig.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.AuditLogConfig
+ fullName: google.cloud.pubsub_v1.types.AuditLogConfig
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: AuditLogConfig
+ source:
+ id: AuditLogConfig
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.AuditLogConfig` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.AuditLogConfig
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BatchSettings.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BatchSettings.yml
new file mode 100644
index 000000000000..9def7f51f3d6
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BatchSettings.yml
@@ -0,0 +1,129 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.types.BatchSettings
+ - google.cloud.pubsub_v1.types.BatchSettings.max_bytes
+ - google.cloud.pubsub_v1.types.BatchSettings.max_latency
+ - google.cloud.pubsub_v1.types.BatchSettings.max_messages
+ class: google.cloud.pubsub_v1.types.BatchSettings
+ fullName: google.cloud.pubsub_v1.types.BatchSettings
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: BatchSettings
+ source:
+ id: BatchSettings
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 63
+ summary: 'The settings for batch publishing the messages.
+
+
+ '
+ syntax:
+ content: "BatchSettings(\n max_bytes: int = 1000000, max_latency: float = 0.01,\
+ \ max_messages: int = 100\n)"
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.BatchSettings
+- attributes: []
+ class: google.cloud.pubsub_v1.types.BatchSettings
+ fullName: google.cloud.pubsub_v1.types.BatchSettings
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: BatchSettings
+ source:
+ id: BatchSettings
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 63
+ summary: 'Create new instance of BatchSettings(max_bytes, max_latency, max_messages)
+
+
+ '
+ syntax:
+ content: "BatchSettings(\n max_bytes: int = 1000000, max_latency: float = 0.01,\
+ \ max_messages: int = 100\n)"
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.types.BatchSettings
+- attributes: []
+ class: google.cloud.pubsub_v1.types.BatchSettings
+ fullName: google.cloud.pubsub_v1.types.BatchSettings.max_bytes
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: max_bytes
+ source:
+ id: max_bytes
+ path: null
+ startLine: null
+ summary: 'The maximum total size of the messages to collect before automatically
+ publishing the batch, including any byte size overhead of the publish request
+ itself. The maximum value is bound by the server-side limit of 10_000_000 bytes.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.BatchSettings.max_bytes
+- attributes: []
+ class: google.cloud.pubsub_v1.types.BatchSettings
+ fullName: google.cloud.pubsub_v1.types.BatchSettings.max_latency
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: max_latency
+ source:
+ id: max_latency
+ path: null
+ startLine: null
+ summary: 'The maximum number of seconds to wait for additional messages before automatically
+ publishing the batch.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.BatchSettings.max_latency
+- attributes: []
+ class: google.cloud.pubsub_v1.types.BatchSettings
+ fullName: google.cloud.pubsub_v1.types.BatchSettings.max_messages
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: max_messages
+ source:
+ id: max_messages
+ path: null
+ startLine: null
+ summary: 'The maximum number of messages to collect before automatically publishing
+ the batch.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.BatchSettings.max_messages
+references:
+- fullName: google.cloud.pubsub_v1.types.BatchSettings
+ isExternal: false
+ name: BatchSettings
+ parent: google.cloud.pubsub_v1.types.BatchSettings
+ uid: google.cloud.pubsub_v1.types.BatchSettings
+- fullName: google.cloud.pubsub_v1.types.BatchSettings.max_bytes
+ isExternal: false
+ name: max_bytes
+ parent: google.cloud.pubsub_v1.types.BatchSettings
+ uid: google.cloud.pubsub_v1.types.BatchSettings.max_bytes
+- fullName: google.cloud.pubsub_v1.types.BatchSettings.max_latency
+ isExternal: false
+ name: max_latency
+ parent: google.cloud.pubsub_v1.types.BatchSettings
+ uid: google.cloud.pubsub_v1.types.BatchSettings.max_latency
+- fullName: google.cloud.pubsub_v1.types.BatchSettings.max_messages
+ isExternal: false
+ name: max_messages
+ parent: google.cloud.pubsub_v1.types.BatchSettings
+ uid: google.cloud.pubsub_v1.types.BatchSettings.max_messages
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BigQueryConfig.State.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BigQueryConfig.State.yml
new file mode 100644
index 000000000000..e3e78f516848
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BigQueryConfig.State.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.BigQueryConfig.State
+ fullName: google.cloud.pubsub_v1.types.BigQueryConfig.State
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.BigQueryConfig
+ name: State
+ source:
+ id: State
+ path: tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
+ startLine: 1041
+ summary: 'Possible states for a BigQuery subscription.
+
+
+ '
+ syntax:
+ content: State(value)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.BigQueryConfig.State
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BigQueryConfig.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BigQueryConfig.yml
new file mode 100644
index 000000000000..78ac3b945a5e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BigQueryConfig.yml
@@ -0,0 +1,55 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The name of the table to which to write data,\n of the form {projectId}:{datasetId}.{tableId}"
+ id: table
+ var_type: str
+ - description: "When true, use the topic's schema as the\n columns to write to\
+ \ in BigQuery, if it exists."
+ id: use_topic_schema
+ var_type: bool
+ - description: "When true, write the subscription name, message_id,\n publish_time,\
+ \ attributes, and ordering_key to additional\n columns in the table. The subscription\
+ \ name, message_id, and\n publish_time fields are put in their own columns\
+ \ while all\n other message properties (other than data) are written to a\n\
+ \ JSON object in the attributes column."
+ id: write_metadata
+ var_type: bool
+ - description: "When true and use_topic_schema is true, any fields that are\n \
+ \ a part of the topic schema that are not part of the BigQuery\n table schema\
+ \ are dropped when writing to BigQuery.\n Otherwise, the schemas must be kept\
+ \ in sync and any messages\n with extra fields are not written and remain\
+ \ in the\n subscription's backlog."
+ id: drop_unknown_fields
+ var_type: bool
+ - description: "Output only. An output-only field that\n indicates whether or\
+ \ not the subscription can\n receive messages."
+ id: state
+ var_type: google.pubsub_v1.types.BigQueryConfig.State
+ children:
+ - google.cloud.pubsub_v1.types.BigQueryConfig.State
+ class: google.cloud.pubsub_v1.types.BigQueryConfig
+ fullName: google.cloud.pubsub_v1.types.BigQueryConfig
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: BigQueryConfig
+ source:
+ id: BigQueryConfig
+ path: null
+ startLine: null
+ summary: 'Configuration for a BigQuery subscription.
+
+ '
+ syntax:
+ content: BigQueryConfig(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.BigQueryConfig
+references:
+- fullName: google.cloud.pubsub_v1.types.BigQueryConfig.State
+ isExternal: false
+ name: State
+ parent: google.cloud.pubsub_v1.types.BigQueryConfig
+ uid: google.cloud.pubsub_v1.types.BigQueryConfig.State
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Binding.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Binding.yml
new file mode 100644
index 000000000000..a96f4a1a843a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Binding.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.Binding
+ fullName: google.cloud.pubsub_v1.types.Binding
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Binding
+ source:
+ id: Binding
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.Binding` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.Binding
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BindingDelta.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BindingDelta.yml
new file mode 100644
index 000000000000..9ebb7f98e0b8
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.BindingDelta.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.BindingDelta
+ fullName: google.cloud.pubsub_v1.types.BindingDelta
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: BindingDelta
+ source:
+ id: BindingDelta
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.BindingDelta` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.BindingDelta
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry.yml
new file mode 100644
index 000000000000..7becaacc54e2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry
+ fullName: google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ name: LabelsEntry
+ source:
+ id: LabelsEntry
+ path: null
+ startLine: null
+ summary: 'The abstract base class for a message.
+
+ '
+ syntax:
+ content: LabelsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters:
+ - defaultValue: None
+ description: Keys and values corresponding to the fields of the message.
+ id: kwargs
+ var_type: dict
+ - description: A dictionary or message to be used to determine the values for
+ this message.
+ id: mapping
+ var_type: Union[dict, .Message]
+ - description: If True, do not raise errors for unknown fields. Only applied if
+ mapping is a mapping type or there are keyword parameters.
+ id: ignore_unknown_fields
+ var_type: Optional(bool)
+ type: class
+ uid: google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CreateSnapshotRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CreateSnapshotRequest.yml
new file mode 100644
index 000000000000..6b2043b19479
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CreateSnapshotRequest.yml
@@ -0,0 +1,50 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. User-provided name for this snapshot. If the name\n \
+ \ is not provided in the request, the server will assign a\n random name for\
+ \ this snapshot on the same project as the\n subscription. Note that for REST\
+ \ API requests, you must\n specify a name. See the resource name rules. Format\
+ \ is\n projects/{project}/snapshots/{snap}."
+ id: name
+ var_type: str
+ - description: "Required. The subscription whose backlog the snapshot\n retains.\
+ \ Specifically, the created snapshot is guaranteed to\n retain: (a) The existing\
+ \ backlog on the subscription. More\n precisely, this is defined as the messages\
+ \ in the\n subscription's backlog that are unacknowledged upon the\n successful\
+ \ completion of the CreateSnapshot request; as\n well as: (b)\
+ \ Any messages published to the subscription's\n topic following the successful\
+ \ completion of the\n CreateSnapshot request. Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ - description: "See \n Creating and managing labels."
+ id: labels
+ var_type: Mapping[str, str]
+ children:
+ - google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry
+ class: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ fullName: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: CreateSnapshotRequest
+ source:
+ id: CreateSnapshotRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `CreateSnapshot` method.
+
+ '
+ syntax:
+ content: CreateSnapshotRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+references:
+- fullName: google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry
+ isExternal: false
+ name: LabelsEntry
+ parent: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ uid: google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CustomHttpPattern.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CustomHttpPattern.yml
new file mode 100644
index 000000000000..089fc511c8c9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.CustomHttpPattern.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.CustomHttpPattern
+ fullName: google.cloud.pubsub_v1.types.CustomHttpPattern
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: CustomHttpPattern
+ source:
+ id: CustomHttpPattern
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.CustomHttpPattern` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.CustomHttpPattern
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeadLetterPolicy.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeadLetterPolicy.yml
new file mode 100644
index 000000000000..0e332f0d659f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeadLetterPolicy.yml
@@ -0,0 +1,53 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The name of the topic to which dead letter messages should\n be\
+ \ published. Format is\n projects/{project}/topics/{topic}.The\
+ \ Cloud Pub/Sub\n service account associated with the enclosing subscription's\n\
+ \ parent project (i.e.,\n service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com)\n\
+ \ must have permission to Publish() to this topic.\n \n The operation\
+ \ will fail if the topic does not exist. Users\n should ensure that there\
+ \ is a subscription attached to this\n topic since messages published to a\
+ \ topic with no\n subscriptions are lost."
+ id: dead_letter_topic
+ var_type: str
+ - description: "The maximum number of delivery attempts for any message. The\n \
+ \ value must be between 5 and 100.\n \n The number of delivery attempts\
+ \ is defined as 1 + (the sum\n of number of NACKs and number of times the\
+ \ acknowledgement\n deadline has been exceeded for the message).\n \n \
+ \ A NACK is any call to ModifyAckDeadline with a 0 deadline.\n Note that client\
+ \ libraries may automatically extend\n ack_deadlines.\n \n This field\
+ \ will be honored on a best effort basis.\n \n If this parameter is 0, a\
+ \ default value of 5 is used."
+ id: max_delivery_attempts
+ var_type: int
+ children: []
+ class: google.cloud.pubsub_v1.types.DeadLetterPolicy
+ fullName: google.cloud.pubsub_v1.types.DeadLetterPolicy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: DeadLetterPolicy
+ source:
+ id: DeadLetterPolicy
+ path: null
+ startLine: null
+ summary: 'Dead lettering is done on a best effort basis. The same
+
+ message might be dead lettered multiple times.
+
+
+ If validation on any of the fields fails at subscription
+
+ creation/updation, the create/update subscription request will
+
+ fail.
+
+ '
+ syntax:
+ content: DeadLetterPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.DeadLetterPolicy
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteSnapshotRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteSnapshotRequest.yml
new file mode 100644
index 000000000000..af9c27484f5a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteSnapshotRequest.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the snapshot to delete. Format is\n projects/{project}/snapshots/{snap}."
+ id: snapshot
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.DeleteSnapshotRequest
+ fullName: google.cloud.pubsub_v1.types.DeleteSnapshotRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: DeleteSnapshotRequest
+ source:
+ id: DeleteSnapshotRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `DeleteSnapshot` method.
+
+ '
+ syntax:
+ content: DeleteSnapshotRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.DeleteSnapshotRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteSubscriptionRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteSubscriptionRequest.yml
new file mode 100644
index 000000000000..493cfbd6eb58
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteSubscriptionRequest.yml
@@ -0,0 +1,28 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The subscription to delete. Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.DeleteSubscriptionRequest
+ fullName: google.cloud.pubsub_v1.types.DeleteSubscriptionRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: DeleteSubscriptionRequest
+ source:
+ id: DeleteSubscriptionRequest
+ path: null
+ startLine: null
+ summary: 'Request for the DeleteSubscription method.
+
+ '
+ syntax:
+ content: DeleteSubscriptionRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.DeleteSubscriptionRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteTopicRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteTopicRequest.yml
new file mode 100644
index 000000000000..bc46b52163f2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DeleteTopicRequest.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. Name of the topic to delete. Format is\n projects/{project}/topics/{topic}."
+ id: topic
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.DeleteTopicRequest
+ fullName: google.cloud.pubsub_v1.types.DeleteTopicRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: DeleteTopicRequest
+ source:
+ id: DeleteTopicRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `DeleteTopic` method.
+
+ '
+ syntax:
+ content: DeleteTopicRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.DeleteTopicRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange.yml
new file mode 100644
index 000000000000..6403feaf8ebf
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange.yml
@@ -0,0 +1,20 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange
+ fullName: google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.DescriptorProto
+ name: ExtensionRange
+ source:
+ id: ExtensionRange
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.DescriptorProto.ExtensionRange`
+ class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange.yml
new file mode 100644
index 000000000000..62aca0aa8ccf
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange
+ fullName: google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.DescriptorProto
+ name: ReservedRange
+ source:
+ id: ReservedRange
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.DescriptorProto.ReservedRange` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.yml
new file mode 100644
index 000000000000..8312a541fb57
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DescriptorProto.yml
@@ -0,0 +1,31 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange
+ - google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange
+ class: google.cloud.pubsub_v1.types.DescriptorProto
+ fullName: google.cloud.pubsub_v1.types.DescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: DescriptorProto
+ source:
+ id: DescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.DescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.DescriptorProto
+references:
+- fullName: google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange
+ isExternal: false
+ name: ExtensionRange
+ parent: google.cloud.pubsub_v1.types.DescriptorProto
+ uid: google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange
+- fullName: google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange
+ isExternal: false
+ name: ReservedRange
+ parent: google.cloud.pubsub_v1.types.DescriptorProto
+ uid: google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DetachSubscriptionRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DetachSubscriptionRequest.yml
new file mode 100644
index 000000000000..4d100d357a82
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DetachSubscriptionRequest.yml
@@ -0,0 +1,28 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The subscription to detach. Format is\n projects/{project}/subscriptions/{subscription}."
+ id: subscription
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.DetachSubscriptionRequest
+ fullName: google.cloud.pubsub_v1.types.DetachSubscriptionRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: DetachSubscriptionRequest
+ source:
+ id: DetachSubscriptionRequest
+ path: null
+ startLine: null
+ summary: 'Request for the DetachSubscription method.
+
+ '
+ syntax:
+ content: DetachSubscriptionRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.DetachSubscriptionRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DetachSubscriptionResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DetachSubscriptionResponse.yml
new file mode 100644
index 000000000000..cb12aa19a438
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.DetachSubscriptionResponse.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.DetachSubscriptionResponse
+ fullName: google.cloud.pubsub_v1.types.DetachSubscriptionResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: DetachSubscriptionResponse
+ source:
+ id: DetachSubscriptionResponse
+ path: null
+ startLine: null
+ summary: 'Response for the DetachSubscription method.
+
+ Reserved for future use.
+
+ '
+ syntax:
+ content: DetachSubscriptionResponse(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.DetachSubscriptionResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Duration.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Duration.yml
new file mode 100644
index 000000000000..2e46d79cf571
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Duration.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.Duration
+ fullName: google.cloud.pubsub_v1.types.Duration
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Duration
+ source:
+ id: Duration
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.Duration` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.Duration
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Empty.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Empty.yml
new file mode 100644
index 000000000000..a4f041cd46c2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Empty.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.Empty
+ fullName: google.cloud.pubsub_v1.types.Empty
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Empty
+ source:
+ id: Empty
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.Empty` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.Empty
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange.yml
new file mode 100644
index 000000000000..cc588a5dfb28
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange.yml
@@ -0,0 +1,20 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange
+ fullName: google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.EnumDescriptorProto
+ name: EnumReservedRange
+ source:
+ id: EnumReservedRange
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.EnumDescriptorProto.EnumReservedRange`
+ class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumDescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumDescriptorProto.yml
new file mode 100644
index 000000000000..da57d1ff3854
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumDescriptorProto.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange
+ class: google.cloud.pubsub_v1.types.EnumDescriptorProto
+ fullName: google.cloud.pubsub_v1.types.EnumDescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: EnumDescriptorProto
+ source:
+ id: EnumDescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.EnumDescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.EnumDescriptorProto
+references:
+- fullName: google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange
+ isExternal: false
+ name: EnumReservedRange
+ parent: google.cloud.pubsub_v1.types.EnumDescriptorProto
+ uid: google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumOptions.yml
new file mode 100644
index 000000000000..48440c65fad3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumOptions.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.EnumOptions
+ fullName: google.cloud.pubsub_v1.types.EnumOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: EnumOptions
+ source:
+ id: EnumOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.EnumOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.EnumOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumValueDescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumValueDescriptorProto.yml
new file mode 100644
index 000000000000..6cb4a2814484
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumValueDescriptorProto.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.EnumValueDescriptorProto
+ fullName: google.cloud.pubsub_v1.types.EnumValueDescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: EnumValueDescriptorProto
+ source:
+ id: EnumValueDescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.EnumValueDescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.EnumValueDescriptorProto
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumValueOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumValueOptions.yml
new file mode 100644
index 000000000000..c591bed08395
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.EnumValueOptions.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.EnumValueOptions
+ fullName: google.cloud.pubsub_v1.types.EnumValueOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: EnumValueOptions
+ source:
+ id: EnumValueOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.EnumValueOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.EnumValueOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExpirationPolicy.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExpirationPolicy.yml
new file mode 100644
index 000000000000..42752df68d94
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExpirationPolicy.yml
@@ -0,0 +1,34 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Specifies the \"time-to-live\" duration for an associated\n resource.\
+ \ The resource expires if it is not active for a\n period of ttl.\
+ \ The definition of \"activity\" depends on\n the type of the associated resource.\
+ \ The minimum and maximum\n allowed values for ttl depend on\
+ \ the type of the\n associated resource, as well. If ttl is not\
+ \ set, the\n associated resource never expires."
+ id: ttl
+ var_type: google.protobuf.duration_pb2.Duration
+ children: []
+ class: google.cloud.pubsub_v1.types.ExpirationPolicy
+ fullName: google.cloud.pubsub_v1.types.ExpirationPolicy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ExpirationPolicy
+ source:
+ id: ExpirationPolicy
+ path: null
+ startLine: null
+ summary: 'A policy that specifies the conditions for resource
+
+ expiration (i.e., automatic resource deletion).
+
+ '
+ syntax:
+ content: ExpirationPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ExpirationPolicy
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration.yml
new file mode 100644
index 000000000000..0e0e4e59269b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration.yml
@@ -0,0 +1,20 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration
+ fullName: google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ name: Declaration
+ source:
+ id: Declaration
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.ExtensionRangeOptions.Declaration`
+ class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExtensionRangeOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExtensionRangeOptions.yml
new file mode 100644
index 000000000000..63255025ad63
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ExtensionRangeOptions.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration
+ class: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ fullName: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ExtensionRangeOptions
+ source:
+ id: ExtensionRangeOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.ExtensionRangeOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+references:
+- fullName: google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration
+ isExternal: false
+ name: Declaration
+ parent: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ uid: google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSet.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSet.yml
new file mode 100644
index 000000000000..2b7750a03ceb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSet.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FeatureSet
+ fullName: google.cloud.pubsub_v1.types.FeatureSet
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FeatureSet
+ source:
+ id: FeatureSet
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FeatureSet` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FeatureSet
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault.yml
new file mode 100644
index 000000000000..9c5056997811
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault.yml
@@ -0,0 +1,20 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault
+ fullName: google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.FeatureSetDefaults
+ name: FeatureSetEditionDefault
+ source:
+ id: FeatureSetEditionDefault
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault`
+ class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSetDefaults.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSetDefaults.yml
new file mode 100644
index 000000000000..b6c6d9bda2f5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FeatureSetDefaults.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault
+ class: google.cloud.pubsub_v1.types.FeatureSetDefaults
+ fullName: google.cloud.pubsub_v1.types.FeatureSetDefaults
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FeatureSetDefaults
+ source:
+ id: FeatureSetDefaults
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FeatureSetDefaults` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FeatureSetDefaults
+references:
+- fullName: google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault
+ isExternal: false
+ name: FeatureSetEditionDefault
+ parent: google.cloud.pubsub_v1.types.FeatureSetDefaults
+ uid: google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldDescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldDescriptorProto.yml
new file mode 100644
index 000000000000..8ed174ee0e7e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldDescriptorProto.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FieldDescriptorProto
+ fullName: google.cloud.pubsub_v1.types.FieldDescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FieldDescriptorProto
+ source:
+ id: FieldDescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FieldDescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FieldDescriptorProto
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldMask.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldMask.yml
new file mode 100644
index 000000000000..1e8ec49014cb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldMask.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FieldMask
+ fullName: google.cloud.pubsub_v1.types.FieldMask
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FieldMask
+ source:
+ id: FieldMask
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FieldMask` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FieldMask
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldOptions.EditionDefault.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldOptions.EditionDefault.yml
new file mode 100644
index 000000000000..625e4fd8e670
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldOptions.EditionDefault.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FieldOptions.EditionDefault
+ fullName: google.cloud.pubsub_v1.types.FieldOptions.EditionDefault
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.FieldOptions
+ name: EditionDefault
+ source:
+ id: EditionDefault
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FieldOptions.EditionDefault` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FieldOptions.EditionDefault
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldOptions.yml
new file mode 100644
index 000000000000..933aeec7c2c0
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FieldOptions.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.FieldOptions.EditionDefault
+ class: google.cloud.pubsub_v1.types.FieldOptions
+ fullName: google.cloud.pubsub_v1.types.FieldOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FieldOptions
+ source:
+ id: FieldOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FieldOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FieldOptions
+references:
+- fullName: google.cloud.pubsub_v1.types.FieldOptions.EditionDefault
+ isExternal: false
+ name: EditionDefault
+ parent: google.cloud.pubsub_v1.types.FieldOptions
+ uid: google.cloud.pubsub_v1.types.FieldOptions.EditionDefault
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileDescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileDescriptorProto.yml
new file mode 100644
index 000000000000..72d8d312a393
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileDescriptorProto.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FileDescriptorProto
+ fullName: google.cloud.pubsub_v1.types.FileDescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FileDescriptorProto
+ source:
+ id: FileDescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FileDescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FileDescriptorProto
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileDescriptorSet.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileDescriptorSet.yml
new file mode 100644
index 000000000000..6cbf9e913f7e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileDescriptorSet.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FileDescriptorSet
+ fullName: google.cloud.pubsub_v1.types.FileDescriptorSet
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FileDescriptorSet
+ source:
+ id: FileDescriptorSet
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FileDescriptorSet` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FileDescriptorSet
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileOptions.yml
new file mode 100644
index 000000000000..c7de99dcf345
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FileOptions.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.FileOptions
+ fullName: google.cloud.pubsub_v1.types.FileOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FileOptions
+ source:
+ id: FileOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.FileOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.FileOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FlowControl.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FlowControl.yml
new file mode 100644
index 000000000000..4d14b5872913
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.FlowControl.yml
@@ -0,0 +1,185 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.types.FlowControl
+ - google.cloud.pubsub_v1.types.FlowControl.max_bytes
+ - google.cloud.pubsub_v1.types.FlowControl.max_duration_per_lease_extension
+ - google.cloud.pubsub_v1.types.FlowControl.max_lease_duration
+ - google.cloud.pubsub_v1.types.FlowControl.max_messages
+ - google.cloud.pubsub_v1.types.FlowControl.min_duration_per_lease_extension
+ class: google.cloud.pubsub_v1.types.FlowControl
+ fullName: google.cloud.pubsub_v1.types.FlowControl
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FlowControl
+ source:
+ id: FlowControl
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 142
+ summary: 'The settings for controlling the rate at which messages are pulled
+
+ with an asynchronous subscription.
+
+
+ '
+ syntax:
+ content: "FlowControl(\n max_bytes: int = 104857600,\n max_messages: int\
+ \ = 1000,\n max_lease_duration: float = 3600,\n min_duration_per_lease_extension:\
+ \ float = 0,\n max_duration_per_lease_extension: float = 0,\n)"
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.FlowControl
+- attributes: []
+ class: google.cloud.pubsub_v1.types.FlowControl
+ fullName: google.cloud.pubsub_v1.types.FlowControl
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: FlowControl
+ source:
+ id: FlowControl
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 142
+ summary: 'Create new instance of FlowControl(max_bytes, max_messages, max_lease_duration,
+ min_duration_per_lease_extension, max_duration_per_lease_extension)
+
+
+ '
+ syntax:
+ content: "FlowControl(\n max_bytes: int = 104857600,\n max_messages: int\
+ \ = 1000,\n max_lease_duration: float = 3600,\n min_duration_per_lease_extension:\
+ \ float = 0,\n max_duration_per_lease_extension: float = 0,\n)"
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.types.FlowControl
+- attributes: []
+ class: google.cloud.pubsub_v1.types.FlowControl
+ fullName: google.cloud.pubsub_v1.types.FlowControl.max_bytes
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: max_bytes
+ source:
+ id: max_bytes
+ path: null
+ startLine: null
+ summary: 'The maximum total size of received - but not yet processed - messages
+ before pausing the message stream.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_bytes
+- attributes: []
+ class: google.cloud.pubsub_v1.types.FlowControl
+ fullName: google.cloud.pubsub_v1.types.FlowControl.max_duration_per_lease_extension
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: max_duration_per_lease_extension
+ source:
+ id: max_duration_per_lease_extension
+ path: null
+ startLine: null
+ summary: 'The max amount of time in seconds for a single lease extension attempt.
+ Bounds the delay before a message redelivery if the subscriber fails to extend
+ the deadline. Must be between 10 and 600 (inclusive). Ignored if set to 0.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_duration_per_lease_extension
+- attributes: []
+ class: google.cloud.pubsub_v1.types.FlowControl
+ fullName: google.cloud.pubsub_v1.types.FlowControl.max_lease_duration
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: max_lease_duration
+ source:
+ id: max_lease_duration
+ path: null
+ startLine: null
+ summary: 'The maximum amount of time in seconds to hold a lease on a message before
+ dropping it from the lease management.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_lease_duration
+- attributes: []
+ class: google.cloud.pubsub_v1.types.FlowControl
+ fullName: google.cloud.pubsub_v1.types.FlowControl.max_messages
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: max_messages
+ source:
+ id: max_messages
+ path: null
+ startLine: null
+ summary: 'The maximum number of received - but not yet processed - messages before
+ pausing the message stream.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_messages
+- attributes: []
+ class: google.cloud.pubsub_v1.types.FlowControl
+ fullName: google.cloud.pubsub_v1.types.FlowControl.min_duration_per_lease_extension
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: min_duration_per_lease_extension
+ source:
+ id: min_duration_per_lease_extension
+ path: null
+ startLine: null
+ summary: 'The min amount of time in seconds for a single lease extension attempt.
+ Must be between 10 and 600 (inclusive). Ignored by default, but set to 60 seconds
+ if the subscription has exactly-once delivery enabled.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.FlowControl.min_duration_per_lease_extension
+references:
+- fullName: google.cloud.pubsub_v1.types.FlowControl
+ isExternal: false
+ name: FlowControl
+ parent: google.cloud.pubsub_v1.types.FlowControl
+ uid: google.cloud.pubsub_v1.types.FlowControl
+- fullName: google.cloud.pubsub_v1.types.FlowControl.max_bytes
+ isExternal: false
+ name: max_bytes
+ parent: google.cloud.pubsub_v1.types.FlowControl
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_bytes
+- fullName: google.cloud.pubsub_v1.types.FlowControl.max_duration_per_lease_extension
+ isExternal: false
+ name: max_duration_per_lease_extension
+ parent: google.cloud.pubsub_v1.types.FlowControl
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_duration_per_lease_extension
+- fullName: google.cloud.pubsub_v1.types.FlowControl.max_lease_duration
+ isExternal: false
+ name: max_lease_duration
+ parent: google.cloud.pubsub_v1.types.FlowControl
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_lease_duration
+- fullName: google.cloud.pubsub_v1.types.FlowControl.max_messages
+ isExternal: false
+ name: max_messages
+ parent: google.cloud.pubsub_v1.types.FlowControl
+ uid: google.cloud.pubsub_v1.types.FlowControl.max_messages
+- fullName: google.cloud.pubsub_v1.types.FlowControl.min_duration_per_lease_extension
+ isExternal: false
+ name: min_duration_per_lease_extension
+ parent: google.cloud.pubsub_v1.types.FlowControl
+ uid: google.cloud.pubsub_v1.types.FlowControl.min_duration_per_lease_extension
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation.yml
new file mode 100644
index 000000000000..141074676435
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation
+ fullName: google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ name: Annotation
+ source:
+ id: Annotation
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.GeneratedCodeInfo.Annotation` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GeneratedCodeInfo.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GeneratedCodeInfo.yml
new file mode 100644
index 000000000000..3953415423d9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GeneratedCodeInfo.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation
+ class: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ fullName: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: GeneratedCodeInfo
+ source:
+ id: GeneratedCodeInfo
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.GeneratedCodeInfo` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+references:
+- fullName: google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation
+ isExternal: false
+ name: Annotation
+ parent: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ uid: google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetIamPolicyRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetIamPolicyRequest.yml
new file mode 100644
index 000000000000..f0d31e1fd442
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetIamPolicyRequest.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.GetIamPolicyRequest
+ fullName: google.cloud.pubsub_v1.types.GetIamPolicyRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: GetIamPolicyRequest
+ source:
+ id: GetIamPolicyRequest
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.GetIamPolicyRequest` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.GetIamPolicyRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetSnapshotRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetSnapshotRequest.yml
new file mode 100644
index 000000000000..f9fd09728177
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetSnapshotRequest.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the snapshot to get. Format is\n projects/{project}/snapshots/{snap}."
+ id: snapshot
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.GetSnapshotRequest
+ fullName: google.cloud.pubsub_v1.types.GetSnapshotRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: GetSnapshotRequest
+ source:
+ id: GetSnapshotRequest
+ path: null
+ startLine: null
+ summary: 'Request for the GetSnapshot method.
+
+ '
+ syntax:
+ content: GetSnapshotRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.GetSnapshotRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetSubscriptionRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetSubscriptionRequest.yml
new file mode 100644
index 000000000000..0db27640df60
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetSubscriptionRequest.yml
@@ -0,0 +1,28 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the subscription to get. Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.GetSubscriptionRequest
+ fullName: google.cloud.pubsub_v1.types.GetSubscriptionRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: GetSubscriptionRequest
+ source:
+ id: GetSubscriptionRequest
+ path: null
+ startLine: null
+ summary: 'Request for the GetSubscription method.
+
+ '
+ syntax:
+ content: GetSubscriptionRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.GetSubscriptionRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetTopicRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetTopicRequest.yml
new file mode 100644
index 000000000000..a250e056c90f
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.GetTopicRequest.yml
@@ -0,0 +1,27 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the topic to get. Format is\n projects/{project}/topics/{topic}."
+ id: topic
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.GetTopicRequest
+ fullName: google.cloud.pubsub_v1.types.GetTopicRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: GetTopicRequest
+ source:
+ id: GetTopicRequest
+ path: null
+ startLine: null
+ summary: 'Request for the GetTopic method.
+
+ '
+ syntax:
+ content: GetTopicRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.GetTopicRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Http.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Http.yml
new file mode 100644
index 000000000000..3e36fff6e386
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Http.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.Http
+ fullName: google.cloud.pubsub_v1.types.Http
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Http
+ source:
+ id: Http
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.Http` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.Http
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.HttpRule.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.HttpRule.yml
new file mode 100644
index 000000000000..2b260a77bb4d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.HttpRule.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.HttpRule
+ fullName: google.cloud.pubsub_v1.types.HttpRule
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: HttpRule
+ source:
+ id: HttpRule
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.HttpRule` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.HttpRule
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.LimitExceededBehavior.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.LimitExceededBehavior.yml
new file mode 100644
index 000000000000..b4fa451577ba
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.LimitExceededBehavior.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.LimitExceededBehavior
+ fullName: google.cloud.pubsub_v1.types.LimitExceededBehavior
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: LimitExceededBehavior
+ source:
+ id: LimitExceededBehavior
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 87
+ summary: 'The possible actions when exceeding the publish flow control limits.
+
+
+ '
+ syntax:
+ content: LimitExceededBehavior(value)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.LimitExceededBehavior
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSnapshotsRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSnapshotsRequest.yml
new file mode 100644
index 000000000000..4f992b6a2628
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSnapshotsRequest.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the project in which to list\n snapshots.\
+ \ Format is projects/{project-id}."
+ id: project
+ var_type: str
+ - description: Maximum number of snapshots to return.
+ id: page_size
+ var_type: int
+ - description: "The value returned by the last ListSnapshotsResponse;\n\
+ \ indicates that this is a continuation of a prior\n ListSnapshots\
+ \ call, and that the system should return\n the next page of data."
+ id: page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListSnapshotsRequest
+ fullName: google.cloud.pubsub_v1.types.ListSnapshotsRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListSnapshotsRequest
+ source:
+ id: ListSnapshotsRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `ListSnapshots` method.
+
+ '
+ syntax:
+ content: ListSnapshotsRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListSnapshotsRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSnapshotsResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSnapshotsResponse.yml
new file mode 100644
index 000000000000..b8dbb557d896
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSnapshotsResponse.yml
@@ -0,0 +1,31 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: The resulting snapshots.
+ id: snapshots
+ var_type: Sequence[google.pubsub_v1.types.Snapshot]
+ - description: "If not empty, indicates that there may be more snapshot that\n \
+ \ match the request; this value should be passed in a new\n ListSnapshotsRequest."
+ id: next_page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListSnapshotsResponse
+ fullName: google.cloud.pubsub_v1.types.ListSnapshotsResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListSnapshotsResponse
+ source:
+ id: ListSnapshotsResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `ListSnapshots` method.
+
+ '
+ syntax:
+ content: ListSnapshotsResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListSnapshotsResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSubscriptionsRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSubscriptionsRequest.yml
new file mode 100644
index 000000000000..0582449645f1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSubscriptionsRequest.yml
@@ -0,0 +1,37 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the project in which to list\n subscriptions.\
+ \ Format is projects/{project-id}."
+ id: project
+ var_type: str
+ - description: Maximum number of subscriptions to return.
+ id: page_size
+ var_type: int
+ - description: "The value returned by the last\n ListSubscriptionsResponse;\
+ \ indicates that this is a\n continuation of a prior ListSubscriptions\
+ \ call, and that\n the system should return the next page of data."
+ id: page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListSubscriptionsRequest
+ fullName: google.cloud.pubsub_v1.types.ListSubscriptionsRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListSubscriptionsRequest
+ source:
+ id: ListSubscriptionsRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `ListSubscriptions` method.
+
+ '
+ syntax:
+ content: ListSubscriptionsRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListSubscriptionsRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSubscriptionsResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSubscriptionsResponse.yml
new file mode 100644
index 000000000000..eda5eac069a2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListSubscriptionsResponse.yml
@@ -0,0 +1,33 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: The subscriptions that match the request.
+ id: subscriptions
+ var_type: Sequence[google.pubsub_v1.types.Subscription]
+ - description: "If not empty, indicates that there may be more subscriptions\n \
+ \ that match the request; this value should be passed in a new\n ListSubscriptionsRequest\
+ \ to get more subscriptions."
+ id: next_page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListSubscriptionsResponse
+ fullName: google.cloud.pubsub_v1.types.ListSubscriptionsResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListSubscriptionsResponse
+ source:
+ id: ListSubscriptionsResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `ListSubscriptions` method.
+
+ '
+ syntax:
+ content: ListSubscriptionsResponse(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListSubscriptionsResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest.yml
new file mode 100644
index 000000000000..7d2f7e0c161d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest.yml
@@ -0,0 +1,37 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the topic that snapshots are attached\n \
+ \ to. Format is projects/{project}/topics/{topic}."
+ id: topic
+ var_type: str
+ - description: Maximum number of snapshot names to return.
+ id: page_size
+ var_type: int
+ - description: "The value returned by the last\n ListTopicSnapshotsResponse;\
+ \ indicates that this is a\n continuation of a prior ListTopicSnapshots\
+ \ call, and\n that the system should return the next page of data."
+ id: page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest
+ fullName: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListTopicSnapshotsRequest
+ source:
+ id: ListTopicSnapshotsRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `ListTopicSnapshots` method.
+
+ '
+ syntax:
+ content: ListTopicSnapshotsRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse.yml
new file mode 100644
index 000000000000..80b5e7b987be
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse.yml
@@ -0,0 +1,33 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The names of the snapshots that match the\n request."
+ id: snapshots
+ var_type: Sequence[str]
+ - description: "If not empty, indicates that there may be more snapshots\n that\
+ \ match the request; this value should be passed in a new\n ListTopicSnapshotsRequest\
+ \ to get more snapshots."
+ id: next_page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse
+ fullName: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListTopicSnapshotsResponse
+ source:
+ id: ListTopicSnapshotsResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `ListTopicSnapshots` method.
+
+ '
+ syntax:
+ content: ListTopicSnapshotsResponse(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest.yml
new file mode 100644
index 000000000000..3a159d1a3c38
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest.yml
@@ -0,0 +1,37 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the topic that subscriptions are\n attached\
+ \ to. Format is\n projects/{project}/topics/{topic}."
+ id: topic
+ var_type: str
+ - description: "Maximum number of subscription names to\n return."
+ id: page_size
+ var_type: int
+ - description: "The value returned by the last\n ListTopicSubscriptionsResponse;\
+ \ indicates that this is a\n continuation of a prior ListTopicSubscriptions\
+ \ call, and\n that the system should return the next page of data."
+ id: page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest
+ fullName: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListTopicSubscriptionsRequest
+ source:
+ id: ListTopicSubscriptionsRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `ListTopicSubscriptions` method.
+
+ '
+ syntax:
+ content: "ListTopicSubscriptionsRequest(\n mapping=None, *, ignore_unknown_fields=False,\
+ \ **kwargs\n)"
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse.yml
new file mode 100644
index 000000000000..6b3f8390cd54
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse.yml
@@ -0,0 +1,34 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The names of subscriptions attached to the\n topic specified in\
+ \ the request."
+ id: subscriptions
+ var_type: Sequence[str]
+ - description: "If not empty, indicates that there may be more subscriptions\n \
+ \ that match the request; this value should be passed in a new\n ListTopicSubscriptionsRequest\
+ \ to get more subscriptions."
+ id: next_page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse
+ fullName: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListTopicSubscriptionsResponse
+ source:
+ id: ListTopicSubscriptionsResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `ListTopicSubscriptions` method.
+
+ '
+ syntax:
+ content: "ListTopicSubscriptionsResponse(\n mapping=None, *, ignore_unknown_fields=False,\
+ \ **kwargs\n)"
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicsRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicsRequest.yml
new file mode 100644
index 000000000000..50cc8063484e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicsRequest.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the project in which to list topics.\n Format\
+ \ is projects/{project-id}."
+ id: project
+ var_type: str
+ - description: Maximum number of topics to return.
+ id: page_size
+ var_type: int
+ - description: "The value returned by the last ListTopicsResponse;\n\
+ \ indicates that this is a continuation of a prior\n ListTopics\
+ \ call, and that the system should return the\n next page of data."
+ id: page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListTopicsRequest
+ fullName: google.cloud.pubsub_v1.types.ListTopicsRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListTopicsRequest
+ source:
+ id: ListTopicsRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `ListTopics` method.
+
+ '
+ syntax:
+ content: ListTopicsRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListTopicsRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicsResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicsResponse.yml
new file mode 100644
index 000000000000..d51f6327d743
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ListTopicsResponse.yml
@@ -0,0 +1,31 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: The resulting topics.
+ id: topics
+ var_type: Sequence[google.pubsub_v1.types.Topic]
+ - description: "If not empty, indicates that there may be more topics that\n match\
+ \ the request; this value should be passed in a new\n ListTopicsRequest."
+ id: next_page_token
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.ListTopicsResponse
+ fullName: google.cloud.pubsub_v1.types.ListTopicsResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ListTopicsResponse
+ source:
+ id: ListTopicsResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `ListTopics` method.
+
+ '
+ syntax:
+ content: ListTopicsResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ListTopicsResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MessageOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MessageOptions.yml
new file mode 100644
index 000000000000..13a622ca0e75
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MessageOptions.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.MessageOptions
+ fullName: google.cloud.pubsub_v1.types.MessageOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: MessageOptions
+ source:
+ id: MessageOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.MessageOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.MessageOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MessageStoragePolicy.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MessageStoragePolicy.yml
new file mode 100644
index 000000000000..b131f27475ef
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MessageStoragePolicy.yml
@@ -0,0 +1,33 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "A list of IDs of GCP regions where messages\n that are published\
+ \ to the topic may be persisted\n in storage. Messages published by publishers\n\
+ \ running in non-allowed GCP regions (or running\n outside of GCP altogether)\
+ \ will be routed for\n storage in one of the allowed regions. An empty\n \
+ \ list means that no regions are allowed, and is\n not a valid configuration."
+ id: allowed_persistence_regions
+ var_type: Sequence[str]
+ children: []
+ class: google.cloud.pubsub_v1.types.MessageStoragePolicy
+ fullName: google.cloud.pubsub_v1.types.MessageStoragePolicy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: MessageStoragePolicy
+ source:
+ id: MessageStoragePolicy
+ path: null
+ startLine: null
+ summary: 'A policy constraining the storage of messages published to
+
+ the topic.
+
+ '
+ syntax:
+ content: MessageStoragePolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.MessageStoragePolicy
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MethodDescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MethodDescriptorProto.yml
new file mode 100644
index 000000000000..29cad73ce1ee
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MethodDescriptorProto.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.MethodDescriptorProto
+ fullName: google.cloud.pubsub_v1.types.MethodDescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: MethodDescriptorProto
+ source:
+ id: MethodDescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.MethodDescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.MethodDescriptorProto
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MethodOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MethodOptions.yml
new file mode 100644
index 000000000000..25519e1129ca
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.MethodOptions.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.MethodOptions
+ fullName: google.cloud.pubsub_v1.types.MethodOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: MethodOptions
+ source:
+ id: MethodOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.MethodOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.MethodOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest.yml
new file mode 100644
index 000000000000..c011de431220
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest.yml
@@ -0,0 +1,41 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the subscription. Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ - description: Required. List of acknowledgment IDs.
+ id: ack_ids
+ var_type: Sequence[str]
+ - description: "Required. The new ack deadline with respect to the time this\n \
+ \ request was sent to the Pub/Sub system. For example, if the\n value is\
+ \ 10, the new ack deadline will expire 10 seconds\n after the ModifyAckDeadline\
+ \ call was made. Specifying\n zero might immediately make the message available\
+ \ for\n delivery to another subscriber client. This typically\n results\
+ \ in an increase in the rate of message redeliveries\n (that is, duplicates).\
+ \ The minimum deadline you can specify\n is 0 seconds. The maximum deadline\
+ \ you can specify is 600\n seconds (10 minutes)."
+ id: ack_deadline_seconds
+ var_type: int
+ children: []
+ class: google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest
+ fullName: google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ModifyAckDeadlineRequest
+ source:
+ id: ModifyAckDeadlineRequest
+ path: null
+ startLine: null
+ summary: 'Request for the ModifyAckDeadline method.
+
+ '
+ syntax:
+ content: ModifyAckDeadlineRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ModifyPushConfigRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ModifyPushConfigRequest.yml
new file mode 100644
index 000000000000..744edc5b2cff
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ModifyPushConfigRequest.yml
@@ -0,0 +1,35 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the subscription. Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ - description: "Required. The push configuration for future deliveries.\n \n \
+ \ An empty pushConfig indicates that the Pub/Sub system\n should\
+ \ stop pushing messages from the given subscription and\n allow messages to\
+ \ be pulled and acknowledged - effectively\n pausing the subscription if Pull\
+ \ or StreamingPull is\n not called."
+ id: push_config
+ var_type: google.pubsub_v1.types.PushConfig
+ children: []
+ class: google.cloud.pubsub_v1.types.ModifyPushConfigRequest
+ fullName: google.cloud.pubsub_v1.types.ModifyPushConfigRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ModifyPushConfigRequest
+ source:
+ id: ModifyPushConfigRequest
+ path: null
+ startLine: null
+ summary: 'Request for the ModifyPushConfig method.
+
+ '
+ syntax:
+ content: ModifyPushConfigRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ModifyPushConfigRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.OneofDescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.OneofDescriptorProto.yml
new file mode 100644
index 000000000000..9411314e07af
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.OneofDescriptorProto.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.OneofDescriptorProto
+ fullName: google.cloud.pubsub_v1.types.OneofDescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: OneofDescriptorProto
+ source:
+ id: OneofDescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.OneofDescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.OneofDescriptorProto
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.OneofOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.OneofOptions.yml
new file mode 100644
index 000000000000..2c495ab83139
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.OneofOptions.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.OneofOptions
+ fullName: google.cloud.pubsub_v1.types.OneofOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: OneofOptions
+ source:
+ id: OneofOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.OneofOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.OneofOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Policy.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Policy.yml
new file mode 100644
index 000000000000..d250565eca96
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Policy.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.Policy
+ fullName: google.cloud.pubsub_v1.types.Policy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Policy
+ source:
+ id: Policy
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.Policy` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.Policy
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PolicyDelta.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PolicyDelta.yml
new file mode 100644
index 000000000000..309b5b7b78b6
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PolicyDelta.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.PolicyDelta
+ fullName: google.cloud.pubsub_v1.types.PolicyDelta
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PolicyDelta
+ source:
+ id: PolicyDelta
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.PolicyDelta` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.PolicyDelta
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishFlowControl.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishFlowControl.yml
new file mode 100644
index 000000000000..170614545cdb
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishFlowControl.yml
@@ -0,0 +1,127 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.types.PublishFlowControl
+ - google.cloud.pubsub_v1.types.PublishFlowControl.byte_limit
+ - google.cloud.pubsub_v1.types.PublishFlowControl.limit_exceeded_behavior
+ - google.cloud.pubsub_v1.types.PublishFlowControl.message_limit
+ class: google.cloud.pubsub_v1.types.PublishFlowControl
+ fullName: google.cloud.pubsub_v1.types.PublishFlowControl
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PublishFlowControl
+ source:
+ id: PublishFlowControl
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 95
+ summary: 'The client flow control settings for message publishing.
+
+
+ '
+ syntax:
+ content: "PublishFlowControl(\n message_limit: int = 1000,\n byte_limit:\
+ \ int = 10000000,\n limit_exceeded_behavior: google.cloud.pubsub_v1.types.LimitExceededBehavior\
+ \ = LimitExceededBehavior.IGNORE,\n)"
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublishFlowControl
+ fullName: google.cloud.pubsub_v1.types.PublishFlowControl
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PublishFlowControl
+ source:
+ id: PublishFlowControl
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 95
+ summary: 'Create new instance of PublishFlowControl(message_limit, byte_limit, limit_exceeded_behavior)
+
+
+ '
+ syntax:
+ content: "PublishFlowControl(\n message_limit: int = 1000,\n byte_limit:\
+ \ int = 10000000,\n limit_exceeded_behavior: google.cloud.pubsub_v1.types.LimitExceededBehavior\
+ \ = LimitExceededBehavior.IGNORE,\n)"
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublishFlowControl
+ fullName: google.cloud.pubsub_v1.types.PublishFlowControl.byte_limit
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: byte_limit
+ source:
+ id: byte_limit
+ path: null
+ startLine: null
+ summary: 'The maximum total size of messages awaiting to be published.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl.byte_limit
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublishFlowControl
+ fullName: google.cloud.pubsub_v1.types.PublishFlowControl.limit_exceeded_behavior
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: limit_exceeded_behavior
+ source:
+ id: limit_exceeded_behavior
+ path: null
+ startLine: null
+ summary: 'The action to take when publish flow control limits are exceeded.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl.limit_exceeded_behavior
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublishFlowControl
+ fullName: google.cloud.pubsub_v1.types.PublishFlowControl.message_limit
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: message_limit
+ source:
+ id: message_limit
+ path: null
+ startLine: null
+ summary: 'The maximum number of messages awaiting to be published.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl.message_limit
+references:
+- fullName: google.cloud.pubsub_v1.types.PublishFlowControl
+ isExternal: false
+ name: PublishFlowControl
+ parent: google.cloud.pubsub_v1.types.PublishFlowControl
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl
+- fullName: google.cloud.pubsub_v1.types.PublishFlowControl.byte_limit
+ isExternal: false
+ name: byte_limit
+ parent: google.cloud.pubsub_v1.types.PublishFlowControl
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl.byte_limit
+- fullName: google.cloud.pubsub_v1.types.PublishFlowControl.limit_exceeded_behavior
+ isExternal: false
+ name: limit_exceeded_behavior
+ parent: google.cloud.pubsub_v1.types.PublishFlowControl
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl.limit_exceeded_behavior
+- fullName: google.cloud.pubsub_v1.types.PublishFlowControl.message_limit
+ isExternal: false
+ name: message_limit
+ parent: google.cloud.pubsub_v1.types.PublishFlowControl
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl.message_limit
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishRequest.yml
new file mode 100644
index 000000000000..fbe241b6e05e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishRequest.yml
@@ -0,0 +1,31 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The messages in the request will be published on\n this\
+ \ topic. Format is projects/{project}/topics/{topic}."
+ id: topic
+ var_type: str
+ - description: Required. The messages to publish.
+ id: messages
+ var_type: Sequence[google.pubsub_v1.types.PubsubMessage]
+ children: []
+ class: google.cloud.pubsub_v1.types.PublishRequest
+ fullName: google.cloud.pubsub_v1.types.PublishRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PublishRequest
+ source:
+ id: PublishRequest
+ path: null
+ startLine: null
+ summary: 'Request for the Publish method.
+
+ '
+ syntax:
+ content: PublishRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PublishRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishResponse.yml
new file mode 100644
index 000000000000..8b7b9c9464b3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublishResponse.yml
@@ -0,0 +1,29 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The server-assigned ID of each published\n message, in the same\
+ \ order as the messages in\n the request. IDs are guaranteed to be unique\n\
+ \ within the topic."
+ id: message_ids
+ var_type: Sequence[str]
+ children: []
+ class: google.cloud.pubsub_v1.types.PublishResponse
+ fullName: google.cloud.pubsub_v1.types.PublishResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PublishResponse
+ source:
+ id: PublishResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `Publish` method.
+
+ '
+ syntax:
+ content: PublishResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PublishResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublisherOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublisherOptions.yml
new file mode 100644
index 000000000000..c171a7a46d65
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PublisherOptions.yml
@@ -0,0 +1,159 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.cloud.pubsub_v1.types.PublisherOptions
+ - google.cloud.pubsub_v1.types.PublisherOptions.enable_message_ordering
+ - google.cloud.pubsub_v1.types.PublisherOptions.flow_control
+ - google.cloud.pubsub_v1.types.PublisherOptions.retry
+ - google.cloud.pubsub_v1.types.PublisherOptions.timeout
+ class: google.cloud.pubsub_v1.types.PublisherOptions
+ fullName: google.cloud.pubsub_v1.types.PublisherOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PublisherOptions
+ source:
+ id: PublisherOptions
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 112
+ summary: 'The options for the publisher client.
+
+
+ '
+ syntax:
+ content: 'PublisherOptions(enable_message_ordering: bool = False, flow_control:
+ google.cloud.pubsub_v1.types.PublishFlowControl = PublishFlowControl(message_limit=1000,
+ byte_limit=10000000, limit_exceeded_behavior=), retry: OptionalRetry = _MethodDefault._DEFAULT_VALUE, timeout:
+ OptionalTimeout = _MethodDefault._DEFAULT_VALUE)'
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PublisherOptions
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublisherOptions
+ fullName: google.cloud.pubsub_v1.types.PublisherOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PublisherOptions
+ source:
+ id: PublisherOptions
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 112
+ summary: 'Create new instance of PublisherOptions(enable_message_ordering, flow_control,
+ retry, timeout)
+
+
+ '
+ syntax:
+ content: 'PublisherOptions(enable_message_ordering: bool = False, flow_control:
+ google.cloud.pubsub_v1.types.PublishFlowControl = PublishFlowControl(message_limit=1000,
+ byte_limit=10000000, limit_exceeded_behavior=), retry: OptionalRetry = _MethodDefault._DEFAULT_VALUE, timeout:
+ OptionalTimeout = _MethodDefault._DEFAULT_VALUE)'
+ parameters: []
+ type: method
+ uid: google.cloud.pubsub_v1.types.PublisherOptions
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublisherOptions
+ fullName: google.cloud.pubsub_v1.types.PublisherOptions.enable_message_ordering
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: enable_message_ordering
+ source:
+ id: enable_message_ordering
+ path: null
+ startLine: null
+ summary: 'Whether to order messages in a batch by a supplied ordering key.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.enable_message_ordering
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublisherOptions
+ fullName: google.cloud.pubsub_v1.types.PublisherOptions.flow_control
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: flow_control
+ source:
+ id: flow_control
+ path: null
+ startLine: null
+ summary: 'Flow control settings for message publishing by the client. By default
+ the publisher client does not do any throttling.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.flow_control
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublisherOptions
+ fullName: google.cloud.pubsub_v1.types.PublisherOptions.retry
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: retry
+ source:
+ id: retry
+ path: null
+ startLine: null
+ summary: 'Retry settings for message publishing by the client. This should be an
+ instance of `google.api_core.retry.Retry`.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.retry
+- attributes: []
+ class: google.cloud.pubsub_v1.types.PublisherOptions
+ fullName: google.cloud.pubsub_v1.types.PublisherOptions.timeout
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: timeout
+ source:
+ id: timeout
+ path: null
+ startLine: null
+ summary: 'Timeout settings for message publishing by the client. It should be compatible
+ with `.pubsub_v1.types.TimeoutType`.
+
+
+ '
+ syntax: {}
+ type: attribute
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.timeout
+references:
+- fullName: google.cloud.pubsub_v1.types.PublisherOptions
+ isExternal: false
+ name: PublisherOptions
+ parent: google.cloud.pubsub_v1.types.PublisherOptions
+ uid: google.cloud.pubsub_v1.types.PublisherOptions
+- fullName: google.cloud.pubsub_v1.types.PublisherOptions.enable_message_ordering
+ isExternal: false
+ name: enable_message_ordering
+ parent: google.cloud.pubsub_v1.types.PublisherOptions
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.enable_message_ordering
+- fullName: google.cloud.pubsub_v1.types.PublisherOptions.flow_control
+ isExternal: false
+ name: flow_control
+ parent: google.cloud.pubsub_v1.types.PublisherOptions
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.flow_control
+- fullName: google.cloud.pubsub_v1.types.PublisherOptions.retry
+ isExternal: false
+ name: retry
+ parent: google.cloud.pubsub_v1.types.PublisherOptions
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.retry
+- fullName: google.cloud.pubsub_v1.types.PublisherOptions.timeout
+ isExternal: false
+ name: timeout
+ parent: google.cloud.pubsub_v1.types.PublisherOptions
+ uid: google.cloud.pubsub_v1.types.PublisherOptions.timeout
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry.yml
new file mode 100644
index 000000000000..5380eabd3d23
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry
+ fullName: google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.PubsubMessage
+ name: AttributesEntry
+ source:
+ id: AttributesEntry
+ path: null
+ startLine: null
+ summary: 'The abstract base class for a message.
+
+ '
+ syntax:
+ content: AttributesEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters:
+ - defaultValue: None
+ description: Keys and values corresponding to the fields of the message.
+ id: kwargs
+ var_type: dict
+ - description: A dictionary or message to be used to determine the values for
+ this message.
+ id: mapping
+ var_type: Union[dict, .Message]
+ - description: If True, do not raise errors for unknown fields. Only applied if
+ mapping is a mapping type or there are keyword parameters.
+ id: ignore_unknown_fields
+ var_type: Optional(bool)
+ type: class
+ uid: google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PubsubMessage.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PubsubMessage.yml
new file mode 100644
index 000000000000..851957aa8716
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PubsubMessage.yml
@@ -0,0 +1,76 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The message data field. If this field is\n empty, the message\
+ \ must contain at least one\n attribute."
+ id: data
+ var_type: bytes
+ - description: "Attributes for this message. If this field is\n empty, the message\
+ \ must contain non-empty data.\n This can be used to filter messages on the\n\
+ \ subscription."
+ id: attributes
+ var_type: Mapping[str, str]
+ - description: "ID of this message, assigned by the server when the message\n \
+ \ is published. Guaranteed to be unique within the topic. This\n value may\
+ \ be read by a subscriber that receives a\n PubsubMessage via\
+ \ a Pull call or a push delivery. It\n must not be populated\
+ \ by the publisher in a Publish\n call."
+ id: message_id
+ var_type: str
+ - description: "The time at which the message was published, populated by\n the\
+ \ server when it receives the Publish call. It must\n not be\
+ \ populated by the publisher in a Publish call."
+ id: publish_time
+ var_type: google.protobuf.timestamp_pb2.Timestamp
+ - description: "If non-empty, identifies related messages for which publish\n \
+ \ order should be respected. If a Subscription has\n enable_message_ordering\
+ \ set to true, messages\n published with the same non-empty ordering_key\
+ \ value\n will be delivered to subscribers in the order in which they\n \
+ \ are received by the Pub/Sub system. All PubsubMessage\\ s\n \
+ \ published in a given PublishRequest must specify the\n same\
+ \ ordering_key value."
+ id: ordering_key
+ var_type: str
+ children:
+ - google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry
+ class: google.cloud.pubsub_v1.types.PubsubMessage
+ fullName: google.cloud.pubsub_v1.types.PubsubMessage
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PubsubMessage
+ source:
+ id: PubsubMessage
+ path: null
+ startLine: null
+ summary: 'A message that is published by publishers and consumed by
+
+ subscribers. The message must contain either a non-empty data field
+
+ or at least one attribute. Note that client libraries represent this
+
+ object differently depending on the language. See the corresponding
+
+ `client library
+
+ documentation `__
+
+ for more information. See [quotas and limits]
+
+ (https://cloud.google.com/pubsub/quotas) for more information about
+
+ message limits.
+
+ '
+ syntax:
+ content: PubsubMessage(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PubsubMessage
+references:
+- fullName: google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry
+ isExternal: false
+ name: AttributesEntry
+ parent: google.cloud.pubsub_v1.types.PubsubMessage
+ uid: google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PullRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PullRequest.yml
new file mode 100644
index 000000000000..3bb2338e5eb3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PullRequest.yml
@@ -0,0 +1,42 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The subscription from which messages should be\n pulled.\
+ \ Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ - description: "Optional. If this field set to true, the system will respond\n \
+ \ immediately even if it there are no messages available to\n return in the\
+ \ Pull response. Otherwise, the system may\n wait (for a bounded\
+ \ amount of time) until at least one\n message is available, rather than returning\
+ \ no messages.\n Warning: setting this field to true is discouraged\n\
+ \ because it adversely impacts the performance of Pull\n operations.\
+ \ We recommend that users do not set this field."
+ id: return_immediately
+ var_type: bool
+ - description: "Required. The maximum number of messages to\n return for this\
+ \ request. Must be a positive\n integer. The Pub/Sub system may return fewer\n\
+ \ than the number specified."
+ id: max_messages
+ var_type: int
+ children: []
+ class: google.cloud.pubsub_v1.types.PullRequest
+ fullName: google.cloud.pubsub_v1.types.PullRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PullRequest
+ source:
+ id: PullRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `Pull` method.
+
+ '
+ syntax:
+ content: PullRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PullRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PullResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PullResponse.yml
new file mode 100644
index 000000000000..ba8c4e590953
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PullResponse.yml
@@ -0,0 +1,30 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Received Pub/Sub messages. The list will be empty if there\n are\
+ \ no more messages available in the backlog. For JSON, the\n response can\
+ \ be entirely empty. The Pub/Sub system may\n return fewer than the maxMessages\
+ \ requested even if\n there are more messages available in the backlog."
+ id: received_messages
+ var_type: Sequence[google.pubsub_v1.types.ReceivedMessage]
+ children: []
+ class: google.cloud.pubsub_v1.types.PullResponse
+ fullName: google.cloud.pubsub_v1.types.PullResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PullResponse
+ source:
+ id: PullResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `Pull` method.
+
+ '
+ syntax:
+ content: PullResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PullResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.AttributesEntry.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.AttributesEntry.yml
new file mode 100644
index 000000000000..1df59b0fe68a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.AttributesEntry.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.PushConfig.AttributesEntry
+ fullName: google.cloud.pubsub_v1.types.PushConfig.AttributesEntry
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.PushConfig
+ name: AttributesEntry
+ source:
+ id: AttributesEntry
+ path: null
+ startLine: null
+ summary: 'The abstract base class for a message.
+
+ '
+ syntax:
+ content: AttributesEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters:
+ - defaultValue: None
+ description: Keys and values corresponding to the fields of the message.
+ id: kwargs
+ var_type: dict
+ - description: A dictionary or message to be used to determine the values for
+ this message.
+ id: mapping
+ var_type: Union[dict, .Message]
+ - description: If True, do not raise errors for unknown fields. Only applied if
+ mapping is a mapping type or there are keyword parameters.
+ id: ignore_unknown_fields
+ var_type: Optional(bool)
+ type: class
+ uid: google.cloud.pubsub_v1.types.PushConfig.AttributesEntry
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.OidcToken.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.OidcToken.yml
new file mode 100644
index 000000000000..19d599d2d083
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.OidcToken.yml
@@ -0,0 +1,40 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "`Service account\n email `__\n\
+ \ to be used for generating the OIDC token. The caller (for\n CreateSubscription,\
+ \ UpdateSubscription, and ModifyPushConfig\n RPCs) must have the iam.serviceAccounts.actAs\
+ \ permission for\n the service account."
+ id: service_account_email
+ var_type: str
+ - description: "Audience to be used when generating OIDC\n token. The audience\
+ \ claim identifies the\n recipients that the JWT is intended for. The\n \
+ \ audience value is a single case-sensitive\n string. Having multiple values\
+ \ (array) for the\n audience field is not supported. More info about\n the\
+ \ OIDC JWT token audience here:\n https://tools.ietf.org/html/rfc7519#section-4.1.3\n\
+ \ Note: if not specified, the Push endpoint URL\n will be used."
+ id: audience
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.PushConfig.OidcToken
+ fullName: google.cloud.pubsub_v1.types.PushConfig.OidcToken
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.PushConfig
+ name: OidcToken
+ source:
+ id: OidcToken
+ path: tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
+ startLine: 960
+ summary: 'Contains information needed for generating an `OpenID Connect
+
+ token `__.
+
+ '
+ syntax:
+ content: OidcToken(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PushConfig.OidcToken
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.yml
new file mode 100644
index 000000000000..08ae73d88dd7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.PushConfig.yml
@@ -0,0 +1,66 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "A URL locating the endpoint to which messages should be\n pushed.\
+ \ For example, a Webhook endpoint might use\n https://example.com/push."
+ id: push_endpoint
+ var_type: str
+ - description: "Endpoint configuration attributes that can be used to\n control\
+ \ different aspects of the message delivery.\n \n The only currently supported\
+ \ attribute is\n x-goog-version, which you can use to change\
+ \ the format\n of the pushed message. This attribute indicates the version\n\
+ \ of the data expected by the endpoint. This controls the\n shape of the\
+ \ pushed message (i.e., its fields and metadata).\n \n If not present during\
+ \ the CreateSubscription call, it\n will default to the version\
+ \ of the Pub/Sub API used to make\n such call. If not present in a ModifyPushConfig\
+ \ call,\n its value will not be changed. GetSubscription calls\n\
+ \ will always return a valid version, even if the subscription\n was created\
+ \ without this attribute.\n \n The only supported values for the x-goog-version\n\
+ \ attribute are:\n \n - v1beta1: uses the push format defined\
+ \ in the v1beta1\n Pub/Sub API.\n - v1 or v1beta2:\
+ \ uses the push format defined in\n the v1 Pub/Sub API.\n \n For example:\n\
+ \ \n .. raw:: html\n \n attributes { \"x-goog-version\"\
+ : \"v1\" } Authorization header in the HTTP request for\n every\
+ \ pushed message.\n \n This field is a member of oneof_ authentication_method."
+ id: oidc_token
+ var_type: google.pubsub_v1.types.PushConfig.OidcToken
+ children:
+ - google.cloud.pubsub_v1.types.PushConfig.AttributesEntry
+ - google.cloud.pubsub_v1.types.PushConfig.OidcToken
+ class: google.cloud.pubsub_v1.types.PushConfig
+ fullName: google.cloud.pubsub_v1.types.PushConfig
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: PushConfig
+ source:
+ id: PushConfig
+ path: null
+ startLine: null
+ summary: 'Configuration for a push delivery endpoint.
+
+
+ .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
+
+ '
+ syntax:
+ content: PushConfig(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.PushConfig
+references:
+- fullName: google.cloud.pubsub_v1.types.PushConfig.AttributesEntry
+ isExternal: false
+ name: AttributesEntry
+ parent: google.cloud.pubsub_v1.types.PushConfig
+ uid: google.cloud.pubsub_v1.types.PushConfig.AttributesEntry
+- fullName: google.cloud.pubsub_v1.types.PushConfig.OidcToken
+ isExternal: false
+ name: OidcToken
+ parent: google.cloud.pubsub_v1.types.PushConfig
+ uid: google.cloud.pubsub_v1.types.PushConfig.OidcToken
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ReceivedMessage.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ReceivedMessage.yml
new file mode 100644
index 000000000000..b9ad553d68d5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ReceivedMessage.yml
@@ -0,0 +1,43 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "This ID can be used to acknowledge the\n received message."
+ id: ack_id
+ var_type: str
+ - description: The message.
+ id: message
+ var_type: google.pubsub_v1.types.PubsubMessage
+ - description: "The approximate number of times that Cloud Pub/Sub has\n attempted\
+ \ to deliver the associated message to a subscriber.\n \n More precisely,\
+ \ this is 1 + (number of NACKs) + (number of\n ack_deadline exceeds) for this\
+ \ message.\n \n A NACK is any call to ModifyAckDeadline with a 0 deadline.\n\
+ \ An ack_deadline exceeds event is whenever a message is not\n acknowledged\
+ \ within ack_deadline. Note that ack_deadline is\n initially Subscription.ackDeadlineSeconds,\
+ \ but may get\n extended automatically by the client library.\n \n Upon\
+ \ the first delivery of a given message,\n delivery_attempt will\
+ \ have a value of 1. The value is\n calculated at best effort and is approximate.\n\
+ \ \n If a DeadLetterPolicy is not set on the subscription, this\n will\
+ \ be 0."
+ id: delivery_attempt
+ var_type: int
+ children: []
+ class: google.cloud.pubsub_v1.types.ReceivedMessage
+ fullName: google.cloud.pubsub_v1.types.ReceivedMessage
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ReceivedMessage
+ source:
+ id: ReceivedMessage
+ path: null
+ startLine: null
+ summary: 'A message and its corresponding acknowledgment ID.
+
+ '
+ syntax:
+ content: ReceivedMessage(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.ReceivedMessage
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.RetryPolicy.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.RetryPolicy.yml
new file mode 100644
index 000000000000..a62249ea43a7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.RetryPolicy.yml
@@ -0,0 +1,53 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "The minimum delay between consecutive\n deliveries of a given\
+ \ message. Value should be\n between 0 and 600 seconds. Defaults to 10\n \
+ \ seconds."
+ id: minimum_backoff
+ var_type: google.protobuf.duration_pb2.Duration
+ - description: "The maximum delay between consecutive\n deliveries of a given\
+ \ message. Value should be\n between 0 and 600 seconds. Defaults to 600\n\
+ \ seconds."
+ id: maximum_backoff
+ var_type: google.protobuf.duration_pb2.Duration
+ children: []
+ class: google.cloud.pubsub_v1.types.RetryPolicy
+ fullName: google.cloud.pubsub_v1.types.RetryPolicy
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: RetryPolicy
+ source:
+ id: RetryPolicy
+ path: null
+ startLine: null
+ summary: 'A policy that specifies how Cloud Pub/Sub retries message delivery.
+
+
+ Retry delay will be exponential based on provided minimum and
+
+ maximum backoffs. https://en.wikipedia.org/wiki/Exponential_backoff.
+
+
+ RetryPolicy will be triggered on NACKs or acknowledgement deadline
+
+ exceeded events for a given message.
+
+
+ Retry Policy is implemented on a best effort basis. At times, the
+
+ delay between consecutive deliveries may not match the
+
+ configuration. That is, delay can be more or less than configured
+
+ backoff.
+
+ '
+ syntax:
+ content: RetryPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.RetryPolicy
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SchemaSettings.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SchemaSettings.yml
new file mode 100644
index 000000000000..e870e9cbff06
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SchemaSettings.yml
@@ -0,0 +1,33 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the schema that messages published\n should\
+ \ be validated against. Format is\n projects/{project}/schemas/{schema}.\
+ \ The value of this\n field will be _deleted-schema_ if the schema\
+ \ has been\n deleted."
+ id: schema
+ var_type: str
+ - description: The encoding of messages validated against schema.
+ id: encoding
+ var_type: google.pubsub_v1.types.Encoding
+ children: []
+ class: google.cloud.pubsub_v1.types.SchemaSettings
+ fullName: google.cloud.pubsub_v1.types.SchemaSettings
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: SchemaSettings
+ source:
+ id: SchemaSettings
+ path: null
+ startLine: null
+ summary: 'Settings for validating messages published against a schema.
+
+ '
+ syntax:
+ content: SchemaSettings(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.SchemaSettings
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SeekRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SeekRequest.yml
new file mode 100644
index 000000000000..20e2e085b122
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SeekRequest.yml
@@ -0,0 +1,57 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: Required. The subscription to affect.
+ id: subscription
+ var_type: str
+ - description: "The time to seek to. Messages retained in the subscription\n that\
+ \ were published before this time are marked as\n acknowledged, and messages\
+ \ retained in the subscription that\n were published after this time are marked\
+ \ as unacknowledged.\n Note that this operation affects only those messages\n\
+ \ retained in the subscription (configured by the combination\n of message_retention_duration\
+ \ and\n retain_acked_messages). For example, if time\n\
+ \ corresponds to a point before the message retention window\n (or to a\
+ \ point before the system's notion of the\n subscription creation time), only\
+ \ retained messages will be\n marked as unacknowledged, and already-expunged\
+ \ messages will\n not be restored.\n \n This field is a member of oneof_\
+ \ target."
+ id: time
+ var_type: google.protobuf.timestamp_pb2.Timestamp
+ - description: "The snapshot to seek to. The snapshot's topic must be the\n same\
+ \ as that of the provided subscription. Format is\n projects/{project}/snapshots/{snap}.\n\
+ \ \n This field is a member of oneof_ target."
+ id: snapshot
+ var_type: str
+ children: []
+ class: google.cloud.pubsub_v1.types.SeekRequest
+ fullName: google.cloud.pubsub_v1.types.SeekRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: SeekRequest
+ source:
+ id: SeekRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `Seek` method.
+
+
+ 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
+
+ '
+ syntax:
+ content: SeekRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.SeekRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SeekResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SeekResponse.yml
new file mode 100644
index 000000000000..00a1d6129096
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SeekResponse.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.SeekResponse
+ fullName: google.cloud.pubsub_v1.types.SeekResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: SeekResponse
+ source:
+ id: SeekResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `Seek` method (this response is empty).
+
+
+ '
+ syntax:
+ content: SeekResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.SeekResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ServiceDescriptorProto.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ServiceDescriptorProto.yml
new file mode 100644
index 000000000000..709a03fea0f5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ServiceDescriptorProto.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.ServiceDescriptorProto
+ fullName: google.cloud.pubsub_v1.types.ServiceDescriptorProto
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ServiceDescriptorProto
+ source:
+ id: ServiceDescriptorProto
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.ServiceDescriptorProto` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.ServiceDescriptorProto
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ServiceOptions.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ServiceOptions.yml
new file mode 100644
index 000000000000..534a70b95e79
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.ServiceOptions.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.ServiceOptions
+ fullName: google.cloud.pubsub_v1.types.ServiceOptions
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: ServiceOptions
+ source:
+ id: ServiceOptions
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.ServiceOptions` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.ServiceOptions
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SetIamPolicyRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SetIamPolicyRequest.yml
new file mode 100644
index 000000000000..85dbfe29fced
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SetIamPolicyRequest.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.SetIamPolicyRequest
+ fullName: google.cloud.pubsub_v1.types.SetIamPolicyRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: SetIamPolicyRequest
+ source:
+ id: SetIamPolicyRequest
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.SetIamPolicyRequest` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.SetIamPolicyRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Snapshot.LabelsEntry.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Snapshot.LabelsEntry.yml
new file mode 100644
index 000000000000..31f3e360788d
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Snapshot.LabelsEntry.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.Snapshot.LabelsEntry
+ fullName: google.cloud.pubsub_v1.types.Snapshot.LabelsEntry
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.Snapshot
+ name: LabelsEntry
+ source:
+ id: LabelsEntry
+ path: null
+ startLine: null
+ summary: 'The abstract base class for a message.
+
+ '
+ syntax:
+ content: LabelsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters:
+ - defaultValue: None
+ description: Keys and values corresponding to the fields of the message.
+ id: kwargs
+ var_type: dict
+ - description: A dictionary or message to be used to determine the values for
+ this message.
+ id: mapping
+ var_type: Union[dict, .Message]
+ - description: If True, do not raise errors for unknown fields. Only applied if
+ mapping is a mapping type or there are keyword parameters.
+ id: ignore_unknown_fields
+ var_type: Optional(bool)
+ type: class
+ uid: google.cloud.pubsub_v1.types.Snapshot.LabelsEntry
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Snapshot.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Snapshot.yml
new file mode 100644
index 000000000000..c9e8f5880b75
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Snapshot.yml
@@ -0,0 +1,60 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: The name of the snapshot.
+ id: name
+ var_type: str
+ - description: "The name of the topic from which this\n snapshot is retaining\
+ \ messages."
+ id: topic
+ var_type: str
+ - description: "The snapshot is guaranteed to exist up until this time. A\n newly-created\
+ \ snapshot expires no later than 7 days from the\n time of its creation. Its\
+ \ exact lifetime is determined at\n creation by the existing backlog in the\
+ \ source subscription.\n Specifically, the lifetime of the snapshot is\n \
+ \ 7 days - (age of oldest unacked message in the subscription).\n\
+ \ For example, consider a subscription whose oldest unacked\n message is\
+ \ 3 days old. If a snapshot is created from this\n subscription, the snapshot\
+ \ -- which will always capture this\n 3-day-old backlog as long as the snapshot\
+ \ exists -- will\n expire in 4 days. The service will refuse to create a\n\
+ \ snapshot that would expire in less than 1 hour after\n creation."
+ id: expire_time
+ var_type: google.protobuf.timestamp_pb2.Timestamp
+ - description: "See [Creating and managing labels]\n (https://cloud.google.com/pubsub/docs/labels)."
+ id: labels
+ var_type: Mapping[str, str]
+ children:
+ - google.cloud.pubsub_v1.types.Snapshot.LabelsEntry
+ class: google.cloud.pubsub_v1.types.Snapshot
+ fullName: google.cloud.pubsub_v1.types.Snapshot
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Snapshot
+ source:
+ id: Snapshot
+ path: null
+ startLine: null
+ summary: 'A snapshot resource. Snapshots are used in
+
+ `Seek `__
+
+ operations, which allow you to manage message acknowledgments in
+
+ bulk. That is, you can set the acknowledgment state of messages in
+
+ an existing subscription to the state captured by a snapshot.
+
+ '
+ syntax:
+ content: Snapshot(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.Snapshot
+references:
+- fullName: google.cloud.pubsub_v1.types.Snapshot.LabelsEntry
+ isExternal: false
+ name: LabelsEntry
+ parent: google.cloud.pubsub_v1.types.Snapshot
+ uid: google.cloud.pubsub_v1.types.Snapshot.LabelsEntry
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SourceCodeInfo.Location.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SourceCodeInfo.Location.yml
new file mode 100644
index 000000000000..de5dea34979b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SourceCodeInfo.Location.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.SourceCodeInfo.Location
+ fullName: google.cloud.pubsub_v1.types.SourceCodeInfo.Location
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.SourceCodeInfo
+ name: Location
+ source:
+ id: Location
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.SourceCodeInfo.Location` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.SourceCodeInfo.Location
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SourceCodeInfo.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SourceCodeInfo.yml
new file mode 100644
index 000000000000..360785c84609
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.SourceCodeInfo.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.SourceCodeInfo.Location
+ class: google.cloud.pubsub_v1.types.SourceCodeInfo
+ fullName: google.cloud.pubsub_v1.types.SourceCodeInfo
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: SourceCodeInfo
+ source:
+ id: SourceCodeInfo
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.SourceCodeInfo` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.SourceCodeInfo
+references:
+- fullName: google.cloud.pubsub_v1.types.SourceCodeInfo.Location
+ isExternal: false
+ name: Location
+ parent: google.cloud.pubsub_v1.types.SourceCodeInfo
+ uid: google.cloud.pubsub_v1.types.SourceCodeInfo.Location
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullRequest.yml
new file mode 100644
index 000000000000..1cd74d5ab4d3
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullRequest.yml
@@ -0,0 +1,99 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The subscription for which to initialize the new\n stream.\
+ \ This must be provided in the first request on the\n stream, and must not\
+ \ be set in subsequent requests from\n client to server. Format is\n projects/{project}/subscriptions/{sub}."
+ id: subscription
+ var_type: str
+ - description: "List of acknowledgement IDs for acknowledging previously\n received\
+ \ messages (received on this stream or a different\n stream). If an ack ID\
+ \ has expired, the corresponding message\n may be redelivered later. Acknowledging\
+ \ a message more than\n once will not result in an error. If the acknowledgement\
+ \ ID\n is malformed, the stream will be aborted with status\n INVALID_ARGUMENT."
+ id: ack_ids
+ var_type: Sequence[str]
+ - description: "The list of new ack deadlines for the IDs listed in\n modify_deadline_ack_ids.\
+ \ The size of this list must be\n the same as the size of modify_deadline_ack_ids.\
+ \ If it\n differs the stream will be aborted with\n INVALID_ARGUMENT.\
+ \ Each element in this list is applied\n to the element in the same position\
+ \ in\n modify_deadline_ack_ids. The new ack deadline is with\n\
+ \ respect to the time this request was sent to the Pub/Sub\n system. Must\
+ \ be >= 0. For example, if the value is 10, the\n new ack deadline will expire\
+ \ 10 seconds after this request\n is received. If the value is 0, the message\
+ \ is immediately\n made available for another streaming or non-streaming pull\n\
+ \ request. If the value is < 0 (an error), the stream will be\n aborted\
+ \ with status INVALID_ARGUMENT."
+ id: modify_deadline_seconds
+ var_type: Sequence[int]
+ - description: "List of acknowledgement IDs whose deadline will be modified\n \
+ \ based on the corresponding element in\n modify_deadline_seconds.\
+ \ This field can be used to\n indicate that more time is needed to process\
+ \ a message by\n the subscriber, or to make the message available for\n \
+ \ redelivery if the processing was interrupted."
+ id: modify_deadline_ack_ids
+ var_type: Sequence[str]
+ - description: "Required. The ack deadline to use for the\n stream. This must\
+ \ be provided in the first\n request on the stream, but it can also be\n \
+ \ updated on subsequent requests from client to\n server. The minimum deadline\
+ \ you can specify is\n 10 seconds. The maximum deadline you can specify\n\
+ \ is 600 seconds (10 minutes)."
+ id: stream_ack_deadline_seconds
+ var_type: int
+ - description: "A unique identifier that is used to distinguish client\n instances\
+ \ from each other. Only needs to be provided on the\n initial request. When\
+ \ a stream disconnects and reconnects\n for the same stream, the client_id\
+ \ should be set to the same\n value so that state associated with the old\
+ \ stream can be\n transferred to the new stream. The same client_id should\
+ \ not\n be used for different client instances."
+ id: client_id
+ var_type: str
+ - description: "Flow control settings for the maximum number of outstanding\n \
+ \ messages. When there are max_outstanding_messages or\n more\
+ \ currently sent to the streaming pull client that have\n not yet been acked\
+ \ or nacked, the server stops sending more\n messages. The sending of messages\
+ \ resumes once the number of\n outstanding messages is less than this value.\
+ \ If the value\n is <= 0, there is no limit to the number of outstanding\n\
+ \ messages. This property can only be set on the initial\n StreamingPullRequest.\
+ \ If it is set on a subsequent request,\n the stream will be aborted with\
+ \ status INVALID_ARGUMENT."
+ id: max_outstanding_messages
+ var_type: int
+ - description: "Flow control settings for the maximum number of outstanding\n \
+ \ bytes. When there are max_outstanding_bytes or more\n worth\
+ \ of messages currently sent to the streaming pull\n client that have not\
+ \ yet been acked or nacked, the server\n will stop sending more messages.\
+ \ The sending of messages\n resumes once the number of outstanding bytes is\
+ \ less than\n this value. If the value is <= 0, there is no limit to the\n\
+ \ number of outstanding bytes. This property can only be set\n on the initial\
+ \ StreamingPullRequest. If it is set on a\n subsequent request, the stream\
+ \ will be aborted with status\n INVALID_ARGUMENT."
+ id: max_outstanding_bytes
+ var_type: int
+ children: []
+ class: google.cloud.pubsub_v1.types.StreamingPullRequest
+ fullName: google.cloud.pubsub_v1.types.StreamingPullRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: StreamingPullRequest
+ source:
+ id: StreamingPullRequest
+ path: null
+ startLine: null
+ summary: 'Request for the `StreamingPull` streaming RPC method. This request
+
+ is used to establish the initial stream as well as to stream
+
+ acknowledgements and ack deadline modifications from the client to
+
+ the server.
+
+ '
+ syntax:
+ content: StreamingPullRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.StreamingPullRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation.yml
new file mode 100644
index 000000000000..4cd6a09de5ca
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation.yml
@@ -0,0 +1,37 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: Successfully processed acknowledgement IDs.
+ id: ack_ids
+ var_type: Sequence[str]
+ - description: "List of acknowledgement IDs that were\n malformed or whose acknowledgement\
+ \ deadline has\n expired."
+ id: invalid_ack_ids
+ var_type: Sequence[str]
+ - description: "List of acknowledgement IDs that were out of\n order."
+ id: unordered_ack_ids
+ var_type: Sequence[str]
+ children: []
+ class: google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+ fullName: google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.StreamingPullResponse
+ name: AcknowledgeConfirmation
+ source:
+ id: AcknowledgeConfirmation
+ path: tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
+ startLine: 1509
+ summary: 'Acknowledgement IDs sent in one or more previous requests to
+
+ acknowledge a previously received message.
+
+ '
+ syntax:
+ content: AcknowledgeConfirmation(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation.yml
new file mode 100644
index 000000000000..f7f18a55b6f7
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation.yml
@@ -0,0 +1,34 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: Successfully processed acknowledgement IDs.
+ id: ack_ids
+ var_type: Sequence[str]
+ - description: "List of acknowledgement IDs that were\n malformed or whose acknowledgement\
+ \ deadline has\n expired."
+ id: invalid_ack_ids
+ var_type: Sequence[str]
+ children: []
+ class: google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+ fullName: google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.StreamingPullResponse
+ name: ModifyAckDeadlineConfirmation
+ source:
+ id: ModifyAckDeadlineConfirmation
+ path: tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
+ startLine: 1538
+ summary: 'Acknowledgement IDs sent in one or more previous requests to
+
+ modify the deadline for a specific message.
+
+ '
+ syntax:
+ content: "ModifyAckDeadlineConfirmation(\n mapping=None, *, ignore_unknown_fields=False,\
+ \ **kwargs\n)"
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties.yml
new file mode 100644
index 000000000000..2b047615b995
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties.yml
@@ -0,0 +1,31 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "True iff exactly once delivery is enabled for\n this subscription."
+ id: exactly_once_delivery_enabled
+ var_type: bool
+ - description: "True iff message ordering is enabled for this\n subscription."
+ id: message_ordering_enabled
+ var_type: bool
+ children: []
+ class: google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
+ fullName: google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.StreamingPullResponse
+ name: SubscriptionProperties
+ source:
+ id: SubscriptionProperties
+ path: tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
+ startLine: 1560
+ summary: 'Subscription properties sent as part of the response.
+
+ '
+ syntax:
+ content: SubscriptionProperties(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.yml
new file mode 100644
index 000000000000..89219b3c3fd2
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.StreamingPullResponse.yml
@@ -0,0 +1,58 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Received Pub/Sub messages. This will not be\n empty."
+ id: received_messages
+ var_type: Sequence[google.pubsub_v1.types.ReceivedMessage]
+ - description: "This field will only be set if\n enable_exactly_once_delivery\
+ \ is set to true."
+ id: acknowledge_confirmation
+ var_type: google.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+ - description: "This field will only be set if\n enable_exactly_once_delivery\
+ \ is set to true."
+ id: modify_ack_deadline_confirmation
+ var_type: google.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+ - description: Properties associated with this subscription.
+ id: subscription_properties
+ var_type: google.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
+ children:
+ - google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+ - google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+ - google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
+ class: google.cloud.pubsub_v1.types.StreamingPullResponse
+ fullName: google.cloud.pubsub_v1.types.StreamingPullResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: StreamingPullResponse
+ source:
+ id: StreamingPullResponse
+ path: null
+ startLine: null
+ summary: 'Response for the `StreamingPull` method. This response is used to
+
+ stream messages from the server to the client.
+
+ '
+ syntax:
+ content: StreamingPullResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse
+references:
+- fullName: google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+ isExternal: false
+ name: AcknowledgeConfirmation
+ parent: google.cloud.pubsub_v1.types.StreamingPullResponse
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+- fullName: google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+ isExternal: false
+ name: ModifyAckDeadlineConfirmation
+ parent: google.cloud.pubsub_v1.types.StreamingPullResponse
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+- fullName: google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
+ isExternal: false
+ name: SubscriptionProperties
+ parent: google.cloud.pubsub_v1.types.StreamingPullResponse
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.LabelsEntry.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.LabelsEntry.yml
new file mode 100644
index 000000000000..b536c277c945
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.LabelsEntry.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.Subscription.LabelsEntry
+ fullName: google.cloud.pubsub_v1.types.Subscription.LabelsEntry
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.Subscription
+ name: LabelsEntry
+ source:
+ id: LabelsEntry
+ path: null
+ startLine: null
+ summary: 'The abstract base class for a message.
+
+ '
+ syntax:
+ content: LabelsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters:
+ - defaultValue: None
+ description: Keys and values corresponding to the fields of the message.
+ id: kwargs
+ var_type: dict
+ - description: A dictionary or message to be used to determine the values for
+ this message.
+ id: mapping
+ var_type: Union[dict, .Message]
+ - description: If True, do not raise errors for unknown fields. Only applied if
+ mapping is a mapping type or there are keyword parameters.
+ id: ignore_unknown_fields
+ var_type: Optional(bool)
+ type: class
+ uid: google.cloud.pubsub_v1.types.Subscription.LabelsEntry
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.State.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.State.yml
new file mode 100644
index 000000000000..ae3565e1f8af
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.State.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.Subscription.State
+ fullName: google.cloud.pubsub_v1.types.Subscription.State
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.Subscription
+ name: State
+ source:
+ id: State
+ path: tests/testdata/gapic-combo/google/pubsub_v1/types/pubsub.py
+ startLine: 717
+ summary: 'Possible states for a subscription.
+
+
+ '
+ syntax:
+ content: State(value)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.Subscription.State
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.yml
new file mode 100644
index 000000000000..f582a2806d3a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Subscription.yml
@@ -0,0 +1,166 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the subscription. It must have the\n format\n\
+ \ \"projects/{project}/subscriptions/{subscription}\".\n {subscription}\
+ \ must start with a letter, and contain\n only letters ([A-Za-z]),\
+ \ numbers ([0-9]), dashes\n (-), underscores (_),\
+ \ periods (.), tildes\n (+)\
+ \ or percent signs (%`). It must be\n between 3 and 255\
+ \ characters in length, and it must not\n start with \"goog\"."
+ id: name
+ var_type: str
+ - description: "Required. The name of the topic from which this subscription\n \
+ \ is receiving messages. Format is\n projects/{project}/topics/{topic}.\
+ \ The value of this\n field will be _deleted-topic_ if the topic\
+ \ has been\n deleted."
+ id: topic
+ var_type: str
+ - description: "If push delivery is used with this subscription, this field\n \
+ \ is used to configure it. Either pushConfig or\n bigQueryConfig\
+ \ can be set, but not both. If both are\n empty, then the subscriber will\
+ \ pull and ack messages using\n API methods."
+ id: push_config
+ var_type: google.pubsub_v1.types.PushConfig
+ - description: "If delivery to BigQuery is used with this subscription, this\n \
+ \ field is used to configure it. Either pushConfig or\n bigQueryConfig\
+ \ can be set, but not both. If both are\n empty, then the subscriber will\
+ \ pull and ack messages using\n API methods."
+ id: bigquery_config
+ var_type: google.pubsub_v1.types.BigQueryConfig
+ - description: "The approximate amount of time (on a best-effort basis)\n Pub/Sub\
+ \ waits for the subscriber to acknowledge receipt\n before resending the message.\
+ \ In the interval after the\n message is delivered and before it is acknowledged,\
+ \ it is\n considered to be outstanding. During that time period, the\n message\
+ \ will not be redelivered (on a best-effort basis).\n \n For pull subscriptions,\
+ \ this value is used as the initial\n value for the ack deadline. To override\
+ \ this value for a\n given message, call ModifyAckDeadline with\
+ \ the\n corresponding ack_id if using non-streaming pull or send\n\
+ \ the ack_id in a StreamingModifyAckDeadlineRequest\
+ \ if\n using streaming pull. The minimum custom deadline you can\n specify\
+ \ is 10 seconds. The maximum custom deadline you can\n specify is 600 seconds\
+ \ (10 minutes). If this parameter is 0,\n a default value of 10 seconds is\
+ \ used.\n \n For push delivery, this value is also used to set the\n request\
+ \ timeout for the call to the push endpoint.\n \n If the subscriber never\
+ \ acknowledges the message, the\n Pub/Sub system will eventually redeliver\
+ \ the message."
+ id: ack_deadline_seconds
+ var_type: int
+ - description: "Indicates whether to retain acknowledged messages. If true,\n \
+ \ then messages are not expunged from the subscription's\n backlog, even if\
+ \ they are acknowledged, until they fall out\n of the message_retention_duration\
+ \ window. This must be\n true if you would like to [Seek to a\
+ \ timestamp]\n (https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)\n\
+ \ in the past to replay previously-acknowledged messages."
+ id: retain_acked_messages
+ var_type: bool
+ - description: "How long to retain unacknowledged messages in the\n subscription's\
+ \ backlog, from the moment a message is\n published. If retain_acked_messages\
+ \ is true, then this\n also configures the retention of acknowledged messages,\
+ \ and\n thus configures how far back in time a Seek can be done.\n\
+ \ Defaults to 7 days. Cannot be more than 7 days or less than\n 10 minutes."
+ id: message_retention_duration
+ var_type: google.protobuf.duration_pb2.Duration
+ - description: "See \n Creating and managing labels."
+ id: labels
+ var_type: Mapping[str, str]
+ - description: "If true, messages published with the same ordering_key\n\
+ \ in PubsubMessage will be delivered to the subscribers in\n\
+ \ the order in which they are received by the Pub/Sub system.\n Otherwise,\
+ \ they may be delivered in any order."
+ id: enable_message_ordering
+ var_type: bool
+ - description: "A policy that specifies the conditions for this\n subscription's\
+ \ expiration. A subscription is considered\n active as long as any connected\
+ \ subscriber is successfully\n consuming messages from the subscription or\
+ \ is issuing\n operations on the subscription. If expiration_policy\
+ \ is\n not set, a *default policy* with ttl of 31 days will be\n\
+ \ used. The minimum allowed value for\n expiration_policy.ttl\
+ \ is 1 day."
+ id: expiration_policy
+ var_type: google.pubsub_v1.types.ExpirationPolicy
+ - description: "An expression written in the Pub/Sub `filter\n language `__.\n\
+ \ If non-empty, then only PubsubMessage\\ s whose\n attributes\
+ \ field matches the filter are delivered on\n this subscription. If empty,\
+ \ then no messages are filtered\n out."
+ id: filter
+ var_type: str
+ - description: "A policy that specifies the conditions for dead lettering\n messages\
+ \ in this subscription. If dead_letter_policy is not\n set, dead lettering\
+ \ is disabled.\n \n The Cloud Pub/Sub service account associated with this\n\
+ \ subscriptions's parent project (i.e.,\n service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com)\n\
+ \ must have permission to Acknowledge() messages on this\n subscription."
+ id: dead_letter_policy
+ var_type: google.pubsub_v1.types.DeadLetterPolicy
+ - description: "A policy that specifies how Pub/Sub retries\n message delivery\
+ \ for this subscription.\n \n If not set, the default retry policy is applied.\n\
+ \ This generally implies that messages will be\n retried as soon as possible\
+ \ for healthy\n subscribers. RetryPolicy will be triggered on\n NACKs or\
+ \ acknowledgement deadline exceeded\n events for a given message."
+ id: retry_policy
+ var_type: google.pubsub_v1.types.RetryPolicy
+ - description: "Indicates whether the subscription is detached from its\n topic.\
+ \ Detached subscriptions don't receive messages from\n their topic and don't\
+ \ retain any backlog. Pull and\n StreamingPull requests\
+ \ will return FAILED_PRECONDITION.\n If the subscription is a push subscription,\
+ \ pushes to the\n endpoint will not be made."
+ id: detached
+ var_type: bool
+ - description: "If true, Pub/Sub provides the following guarantees for the\n delivery\
+ \ of a message with a given value of message_id\n on this subscription:\n\
+ \ \n - The message sent to a subscriber is guaranteed not to be\n \
+ \ resent before the message's acknowledgement deadline\n expires.\n -\
+ \ An acknowledged message will not be resent to a\n subscriber.\n \n\
+ \ Note that subscribers may still receive multiple copies of a\n message\
+ \ when enable_exactly_once_delivery is true if the\n message\
+ \ was published multiple times by a publisher client.\n These copies are considered\
+ \ distinct by Pub/Sub and have\n distinct message_id values."
+ id: enable_exactly_once_delivery
+ var_type: bool
+ - description: "Output only. Indicates the minimum duration for which a\n message\
+ \ is retained after it is published to the\n subscription's topic. If this\
+ \ field is set, messages\n published to the subscription's topic in the last\n\
+ \ topic_message_retention_duration are always available to\n\
+ \ subscribers. See the message_retention_duration field in\n\
+ \ Topic. This field is set only in responses from the\n server;\
+ \ it is ignored if it is set in any requests."
+ id: topic_message_retention_duration
+ var_type: google.protobuf.duration_pb2.Duration
+ - description: "Output only. An output-only field indicating\n whether or not\
+ \ the subscription can receive\n messages."
+ id: state
+ var_type: google.pubsub_v1.types.Subscription.State
+ children:
+ - google.cloud.pubsub_v1.types.Subscription.LabelsEntry
+ - google.cloud.pubsub_v1.types.Subscription.State
+ class: google.cloud.pubsub_v1.types.Subscription
+ fullName: google.cloud.pubsub_v1.types.Subscription
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Subscription
+ source:
+ id: Subscription
+ path: null
+ startLine: null
+ summary: 'A subscription resource.
+
+ '
+ syntax:
+ content: Subscription(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.Subscription
+references:
+- fullName: google.cloud.pubsub_v1.types.Subscription.LabelsEntry
+ isExternal: false
+ name: LabelsEntry
+ parent: google.cloud.pubsub_v1.types.Subscription
+ uid: google.cloud.pubsub_v1.types.Subscription.LabelsEntry
+- fullName: google.cloud.pubsub_v1.types.Subscription.State
+ isExternal: false
+ name: State
+ parent: google.cloud.pubsub_v1.types.Subscription
+ uid: google.cloud.pubsub_v1.types.Subscription.State
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.TestIamPermissionsRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.TestIamPermissionsRequest.yml
new file mode 100644
index 000000000000..5e427bac548e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.TestIamPermissionsRequest.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.TestIamPermissionsRequest
+ fullName: google.cloud.pubsub_v1.types.TestIamPermissionsRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: TestIamPermissionsRequest
+ source:
+ id: TestIamPermissionsRequest
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.TestIamPermissionsRequest` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.TestIamPermissionsRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.TestIamPermissionsResponse.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.TestIamPermissionsResponse.yml
new file mode 100644
index 000000000000..9f0137d5623a
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.TestIamPermissionsResponse.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.TestIamPermissionsResponse
+ fullName: google.cloud.pubsub_v1.types.TestIamPermissionsResponse
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: TestIamPermissionsResponse
+ source:
+ id: TestIamPermissionsResponse
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.TestIamPermissionsResponse` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.TestIamPermissionsResponse
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Timestamp.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Timestamp.yml
new file mode 100644
index 000000000000..bde4052d7977
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Timestamp.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.Timestamp
+ fullName: google.cloud.pubsub_v1.types.Timestamp
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Timestamp
+ source:
+ id: Timestamp
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.Timestamp` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.Timestamp
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Topic.LabelsEntry.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Topic.LabelsEntry.yml
new file mode 100644
index 000000000000..379dbe928281
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Topic.LabelsEntry.yml
@@ -0,0 +1,36 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children: []
+ class: google.cloud.pubsub_v1.types.Topic.LabelsEntry
+ fullName: google.cloud.pubsub_v1.types.Topic.LabelsEntry
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.Topic
+ name: LabelsEntry
+ source:
+ id: LabelsEntry
+ path: null
+ startLine: null
+ summary: 'The abstract base class for a message.
+
+ '
+ syntax:
+ content: LabelsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters:
+ - defaultValue: None
+ description: Keys and values corresponding to the fields of the message.
+ id: kwargs
+ var_type: dict
+ - description: A dictionary or message to be used to determine the values for
+ this message.
+ id: mapping
+ var_type: Union[dict, .Message]
+ - description: If True, do not raise errors for unknown fields. Only applied if
+ mapping is a mapping type or there are keyword parameters.
+ id: ignore_unknown_fields
+ var_type: Optional(bool)
+ type: class
+ uid: google.cloud.pubsub_v1.types.Topic.LabelsEntry
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Topic.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Topic.yml
new file mode 100644
index 000000000000..77f29584fa19
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.Topic.yml
@@ -0,0 +1,69 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: "Required. The name of the topic. It must have the format\n \"\
+ projects/{project}/topics/{topic}\". {topic} must\n start\
+ \ with a letter, and contain only letters\n ([A-Za-z]), numbers\
+ \ ([0-9]), dashes (-),\n underscores (`_),\
+ \ periods (.`), tildes (+)\
+ \ or percent signs (%). It must be between 3 and\n 255 characters\
+ \ in length, and it must not start with\n \"goog\"."
+ id: name
+ var_type: str
+ - description: "See [Creating and managing labels]\n (https://cloud.google.com/pubsub/docs/labels)."
+ id: labels
+ var_type: Mapping[str, str]
+ - description: "Policy constraining the set of Google Cloud\n Platform regions\
+ \ where messages published to the\n topic may be stored. If not present, then\
+ \ no\n constraints are in effect."
+ id: message_storage_policy
+ var_type: google.pubsub_v1.types.MessageStoragePolicy
+ - description: "The resource name of the Cloud KMS CryptoKey to be used to\n protect\
+ \ access to messages published on this topic.\n \n The expected format is\n\
+ \ projects/*/locations/*/keyRings/*/cryptoKeys/*."
+ id: kms_key_name
+ var_type: str
+ - description: "Settings for validating messages published\n against a schema."
+ id: schema_settings
+ var_type: google.pubsub_v1.types.SchemaSettings
+ - description: "Reserved for future use. This field is set\n only in responses\
+ \ from the server; it is ignored\n if it is set in any requests."
+ id: satisfies_pzs
+ var_type: bool
+ - description: "Indicates the minimum duration to retain a message after it\n \
+ \ is published to the topic. If this field is set, messages\n published to\
+ \ the topic in the last\n message_retention_duration are always\
+ \ available to\n subscribers. For instance, it allows any attached\n subscription\
+ \ to `seek to a\n timestamp `__\n\
+ \ that is up to message_retention_duration in the past. If\n\
+ \ this field is not set, message retention is controlled by\n settings on\
+ \ individual subscriptions. Cannot be more than 7\n days or less than 10 minutes."
+ id: message_retention_duration
+ var_type: google.protobuf.duration_pb2.Duration
+ children:
+ - google.cloud.pubsub_v1.types.Topic.LabelsEntry
+ class: google.cloud.pubsub_v1.types.Topic
+ fullName: google.cloud.pubsub_v1.types.Topic
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: Topic
+ source:
+ id: Topic
+ path: null
+ startLine: null
+ summary: 'A topic resource.
+
+ '
+ syntax:
+ content: Topic(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.Topic
+references:
+- fullName: google.cloud.pubsub_v1.types.Topic.LabelsEntry
+ isExternal: false
+ name: LabelsEntry
+ parent: google.cloud.pubsub_v1.types.Topic
+ uid: google.cloud.pubsub_v1.types.Topic.LabelsEntry
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UninterpretedOption.NamePart.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UninterpretedOption.NamePart.yml
new file mode 100644
index 000000000000..2b9d5e24372e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UninterpretedOption.NamePart.yml
@@ -0,0 +1,19 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children: []
+ class: google.cloud.pubsub_v1.types.UninterpretedOption.NamePart
+ fullName: google.cloud.pubsub_v1.types.UninterpretedOption.NamePart
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types.UninterpretedOption
+ name: NamePart
+ source:
+ id: NamePart
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.UninterpretedOption.NamePart` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.UninterpretedOption.NamePart
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UninterpretedOption.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UninterpretedOption.yml
new file mode 100644
index 000000000000..c85326e52aa6
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UninterpretedOption.yml
@@ -0,0 +1,25 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.UninterpretedOption.NamePart
+ class: google.cloud.pubsub_v1.types.UninterpretedOption
+ fullName: google.cloud.pubsub_v1.types.UninterpretedOption
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: UninterpretedOption
+ source:
+ id: UninterpretedOption
+ path: null
+ startLine: null
+ summary: API documentation for `pubsub_v1.types.UninterpretedOption` class.
+ syntax: {}
+ type: class
+ uid: google.cloud.pubsub_v1.types.UninterpretedOption
+references:
+- fullName: google.cloud.pubsub_v1.types.UninterpretedOption.NamePart
+ isExternal: false
+ name: NamePart
+ parent: google.cloud.pubsub_v1.types.UninterpretedOption
+ uid: google.cloud.pubsub_v1.types.UninterpretedOption.NamePart
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateSnapshotRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateSnapshotRequest.yml
new file mode 100644
index 000000000000..31eeaf7d5027
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateSnapshotRequest.yml
@@ -0,0 +1,31 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: Required. The updated snapshot object.
+ id: snapshot
+ var_type: google.pubsub_v1.types.Snapshot
+ - description: "Required. Indicates which fields in the\n provided snapshot to\
+ \ update. Must be specified\n and non-empty."
+ id: update_mask
+ var_type: google.protobuf.field_mask_pb2.FieldMask
+ children: []
+ class: google.cloud.pubsub_v1.types.UpdateSnapshotRequest
+ fullName: google.cloud.pubsub_v1.types.UpdateSnapshotRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: UpdateSnapshotRequest
+ source:
+ id: UpdateSnapshotRequest
+ path: null
+ startLine: null
+ summary: 'Request for the UpdateSnapshot method.
+
+ '
+ syntax:
+ content: UpdateSnapshotRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.UpdateSnapshotRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateSubscriptionRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateSubscriptionRequest.yml
new file mode 100644
index 000000000000..ea0ce13e38c5
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateSubscriptionRequest.yml
@@ -0,0 +1,32 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: Required. The updated subscription object.
+ id: subscription
+ var_type: google.pubsub_v1.types.Subscription
+ - description: "Required. Indicates which fields in the\n provided subscription\
+ \ to update. Must be\n specified and non-empty."
+ id: update_mask
+ var_type: google.protobuf.field_mask_pb2.FieldMask
+ children: []
+ class: google.cloud.pubsub_v1.types.UpdateSubscriptionRequest
+ fullName: google.cloud.pubsub_v1.types.UpdateSubscriptionRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: UpdateSubscriptionRequest
+ source:
+ id: UpdateSubscriptionRequest
+ path: null
+ startLine: null
+ summary: 'Request for the UpdateSubscription method.
+
+ '
+ syntax:
+ content: UpdateSubscriptionRequest(mapping=None, *, ignore_unknown_fields=False,
+ **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.UpdateSubscriptionRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateTopicRequest.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateTopicRequest.yml
new file mode 100644
index 000000000000..e78620ea3d00
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.UpdateTopicRequest.yml
@@ -0,0 +1,35 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes:
+ - description: Required. The updated topic object.
+ id: topic
+ var_type: google.pubsub_v1.types.Topic
+ - description: "Required. Indicates which fields in the provided topic to\n update.\
+ \ Must be specified and non-empty. Note that if\n update_mask\
+ \ contains \"message_storage_policy\" but the\n message_storage_policy\
+ \ is not set in the topic\n provided above, then the updated\
+ \ value is determined by the\n policy configured at the project or organization\
+ \ level."
+ id: update_mask
+ var_type: google.protobuf.field_mask_pb2.FieldMask
+ children: []
+ class: google.cloud.pubsub_v1.types.UpdateTopicRequest
+ fullName: google.cloud.pubsub_v1.types.UpdateTopicRequest
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: UpdateTopicRequest
+ source:
+ id: UpdateTopicRequest
+ path: null
+ startLine: null
+ summary: 'Request for the UpdateTopic method.
+
+ '
+ syntax:
+ content: UpdateTopicRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)
+ parameters: []
+ type: class
+ uid: google.cloud.pubsub_v1.types.UpdateTopicRequest
+references: []
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.yml
new file mode 100644
index 000000000000..209feb0019c0
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.cloud.pubsub_v1.types.yml
@@ -0,0 +1,570 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.cloud.pubsub_v1.types.AcknowledgeRequest
+ - google.cloud.pubsub_v1.types.AuditConfig
+ - google.cloud.pubsub_v1.types.AuditConfigDelta
+ - google.cloud.pubsub_v1.types.AuditData
+ - google.cloud.pubsub_v1.types.AuditLogConfig
+ - google.cloud.pubsub_v1.types.BatchSettings
+ - google.cloud.pubsub_v1.types.BigQueryConfig
+ - google.cloud.pubsub_v1.types.Binding
+ - google.cloud.pubsub_v1.types.BindingDelta
+ - google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ - google.cloud.pubsub_v1.types.CustomHttpPattern
+ - google.cloud.pubsub_v1.types.DeadLetterPolicy
+ - google.cloud.pubsub_v1.types.DeleteSnapshotRequest
+ - google.cloud.pubsub_v1.types.DeleteSubscriptionRequest
+ - google.cloud.pubsub_v1.types.DeleteTopicRequest
+ - google.cloud.pubsub_v1.types.DescriptorProto
+ - google.cloud.pubsub_v1.types.DetachSubscriptionRequest
+ - google.cloud.pubsub_v1.types.DetachSubscriptionResponse
+ - google.cloud.pubsub_v1.types.Duration
+ - google.cloud.pubsub_v1.types.Empty
+ - google.cloud.pubsub_v1.types.EnumDescriptorProto
+ - google.cloud.pubsub_v1.types.EnumOptions
+ - google.cloud.pubsub_v1.types.EnumValueDescriptorProto
+ - google.cloud.pubsub_v1.types.EnumValueOptions
+ - google.cloud.pubsub_v1.types.ExpirationPolicy
+ - google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ - google.cloud.pubsub_v1.types.FeatureSet
+ - google.cloud.pubsub_v1.types.FeatureSetDefaults
+ - google.cloud.pubsub_v1.types.FieldDescriptorProto
+ - google.cloud.pubsub_v1.types.FieldMask
+ - google.cloud.pubsub_v1.types.FieldOptions
+ - google.cloud.pubsub_v1.types.FileDescriptorProto
+ - google.cloud.pubsub_v1.types.FileDescriptorSet
+ - google.cloud.pubsub_v1.types.FileOptions
+ - google.cloud.pubsub_v1.types.FlowControl
+ - google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ - google.cloud.pubsub_v1.types.GetIamPolicyRequest
+ - google.cloud.pubsub_v1.types.GetSnapshotRequest
+ - google.cloud.pubsub_v1.types.GetSubscriptionRequest
+ - google.cloud.pubsub_v1.types.GetTopicRequest
+ - google.cloud.pubsub_v1.types.Http
+ - google.cloud.pubsub_v1.types.HttpRule
+ - google.cloud.pubsub_v1.types.LimitExceededBehavior
+ - google.cloud.pubsub_v1.types.ListSnapshotsRequest
+ - google.cloud.pubsub_v1.types.ListSnapshotsResponse
+ - google.cloud.pubsub_v1.types.ListSubscriptionsRequest
+ - google.cloud.pubsub_v1.types.ListSubscriptionsResponse
+ - google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest
+ - google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse
+ - google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest
+ - google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse
+ - google.cloud.pubsub_v1.types.ListTopicsRequest
+ - google.cloud.pubsub_v1.types.ListTopicsResponse
+ - google.cloud.pubsub_v1.types.MessageOptions
+ - google.cloud.pubsub_v1.types.MessageStoragePolicy
+ - google.cloud.pubsub_v1.types.MethodDescriptorProto
+ - google.cloud.pubsub_v1.types.MethodOptions
+ - google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest
+ - google.cloud.pubsub_v1.types.ModifyPushConfigRequest
+ - google.cloud.pubsub_v1.types.OneofDescriptorProto
+ - google.cloud.pubsub_v1.types.OneofOptions
+ - google.cloud.pubsub_v1.types.Policy
+ - google.cloud.pubsub_v1.types.PolicyDelta
+ - google.cloud.pubsub_v1.types.PublishFlowControl
+ - google.cloud.pubsub_v1.types.PublishRequest
+ - google.cloud.pubsub_v1.types.PublishResponse
+ - google.cloud.pubsub_v1.types.PublisherOptions
+ - google.cloud.pubsub_v1.types.PubsubMessage
+ - google.cloud.pubsub_v1.types.PullRequest
+ - google.cloud.pubsub_v1.types.PullResponse
+ - google.cloud.pubsub_v1.types.PushConfig
+ - google.cloud.pubsub_v1.types.ReceivedMessage
+ - google.cloud.pubsub_v1.types.RetryPolicy
+ - google.cloud.pubsub_v1.types.SchemaSettings
+ - google.cloud.pubsub_v1.types.SeekRequest
+ - google.cloud.pubsub_v1.types.SeekResponse
+ - google.cloud.pubsub_v1.types.ServiceDescriptorProto
+ - google.cloud.pubsub_v1.types.ServiceOptions
+ - google.cloud.pubsub_v1.types.SetIamPolicyRequest
+ - google.cloud.pubsub_v1.types.Snapshot
+ - google.cloud.pubsub_v1.types.SourceCodeInfo
+ - google.cloud.pubsub_v1.types.StreamingPullRequest
+ - google.cloud.pubsub_v1.types.StreamingPullResponse
+ - google.cloud.pubsub_v1.types.Subscription
+ - google.cloud.pubsub_v1.types.TestIamPermissionsRequest
+ - google.cloud.pubsub_v1.types.TestIamPermissionsResponse
+ - google.cloud.pubsub_v1.types.Timestamp
+ - google.cloud.pubsub_v1.types.Topic
+ - google.cloud.pubsub_v1.types.UninterpretedOption
+ - google.cloud.pubsub_v1.types.UpdateSnapshotRequest
+ - google.cloud.pubsub_v1.types.UpdateSubscriptionRequest
+ - google.cloud.pubsub_v1.types.UpdateTopicRequest
+ fullName: google.cloud.pubsub_v1.types
+ langs:
+ - python
+ module: google.cloud.pubsub_v1.types
+ name: types
+ source:
+ id: types
+ path: tests/testdata/gapic-combo/google/cloud/pubsub_v1/types.py
+ startLine: 0
+ summary: API documentation for `pubsub_v1.types` module.
+ syntax: {}
+ type: module
+ uid: google.cloud.pubsub_v1.types
+references:
+- fullName: google.cloud.pubsub_v1.types.AcknowledgeRequest
+ isExternal: false
+ name: AcknowledgeRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.AcknowledgeRequest
+- fullName: google.cloud.pubsub_v1.types.AuditConfig
+ isExternal: false
+ name: AuditConfig
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.AuditConfig
+- fullName: google.cloud.pubsub_v1.types.AuditConfigDelta
+ isExternal: false
+ name: AuditConfigDelta
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.AuditConfigDelta
+- fullName: google.cloud.pubsub_v1.types.AuditData
+ isExternal: false
+ name: AuditData
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.AuditData
+- fullName: google.cloud.pubsub_v1.types.AuditLogConfig
+ isExternal: false
+ name: AuditLogConfig
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.AuditLogConfig
+- fullName: google.cloud.pubsub_v1.types.BatchSettings
+ isExternal: false
+ name: BatchSettings
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.BatchSettings
+- fullName: google.cloud.pubsub_v1.types.BigQueryConfig
+ isExternal: false
+ name: BigQueryConfig
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.BigQueryConfig
+- fullName: google.cloud.pubsub_v1.types.Binding
+ isExternal: false
+ name: Binding
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Binding
+- fullName: google.cloud.pubsub_v1.types.BindingDelta
+ isExternal: false
+ name: BindingDelta
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.BindingDelta
+- fullName: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ isExternal: false
+ name: CreateSnapshotRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+- fullName: google.cloud.pubsub_v1.types.CustomHttpPattern
+ isExternal: false
+ name: CustomHttpPattern
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.CustomHttpPattern
+- fullName: google.cloud.pubsub_v1.types.DeadLetterPolicy
+ isExternal: false
+ name: DeadLetterPolicy
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.DeadLetterPolicy
+- fullName: google.cloud.pubsub_v1.types.DeleteSnapshotRequest
+ isExternal: false
+ name: DeleteSnapshotRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.DeleteSnapshotRequest
+- fullName: google.cloud.pubsub_v1.types.DeleteSubscriptionRequest
+ isExternal: false
+ name: DeleteSubscriptionRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.DeleteSubscriptionRequest
+- fullName: google.cloud.pubsub_v1.types.DeleteTopicRequest
+ isExternal: false
+ name: DeleteTopicRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.DeleteTopicRequest
+- fullName: google.cloud.pubsub_v1.types.DescriptorProto
+ isExternal: false
+ name: DescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.DescriptorProto
+- fullName: google.cloud.pubsub_v1.types.DetachSubscriptionRequest
+ isExternal: false
+ name: DetachSubscriptionRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.DetachSubscriptionRequest
+- fullName: google.cloud.pubsub_v1.types.DetachSubscriptionResponse
+ isExternal: false
+ name: DetachSubscriptionResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.DetachSubscriptionResponse
+- fullName: google.cloud.pubsub_v1.types.Duration
+ isExternal: false
+ name: Duration
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Duration
+- fullName: google.cloud.pubsub_v1.types.Empty
+ isExternal: false
+ name: Empty
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Empty
+- fullName: google.cloud.pubsub_v1.types.EnumDescriptorProto
+ isExternal: false
+ name: EnumDescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.EnumDescriptorProto
+- fullName: google.cloud.pubsub_v1.types.EnumOptions
+ isExternal: false
+ name: EnumOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.EnumOptions
+- fullName: google.cloud.pubsub_v1.types.EnumValueDescriptorProto
+ isExternal: false
+ name: EnumValueDescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.EnumValueDescriptorProto
+- fullName: google.cloud.pubsub_v1.types.EnumValueOptions
+ isExternal: false
+ name: EnumValueOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.EnumValueOptions
+- fullName: google.cloud.pubsub_v1.types.ExpirationPolicy
+ isExternal: false
+ name: ExpirationPolicy
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ExpirationPolicy
+- fullName: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ isExternal: false
+ name: ExtensionRangeOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+- fullName: google.cloud.pubsub_v1.types.FeatureSet
+ isExternal: false
+ name: FeatureSet
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FeatureSet
+- fullName: google.cloud.pubsub_v1.types.FeatureSetDefaults
+ isExternal: false
+ name: FeatureSetDefaults
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FeatureSetDefaults
+- fullName: google.cloud.pubsub_v1.types.FieldDescriptorProto
+ isExternal: false
+ name: FieldDescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FieldDescriptorProto
+- fullName: google.cloud.pubsub_v1.types.FieldMask
+ isExternal: false
+ name: FieldMask
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FieldMask
+- fullName: google.cloud.pubsub_v1.types.FieldOptions
+ isExternal: false
+ name: FieldOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FieldOptions
+- fullName: google.cloud.pubsub_v1.types.FileDescriptorProto
+ isExternal: false
+ name: FileDescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FileDescriptorProto
+- fullName: google.cloud.pubsub_v1.types.FileDescriptorSet
+ isExternal: false
+ name: FileDescriptorSet
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FileDescriptorSet
+- fullName: google.cloud.pubsub_v1.types.FileOptions
+ isExternal: false
+ name: FileOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FileOptions
+- fullName: google.cloud.pubsub_v1.types.FlowControl
+ isExternal: false
+ name: FlowControl
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.FlowControl
+- fullName: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ isExternal: false
+ name: GeneratedCodeInfo
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+- fullName: google.cloud.pubsub_v1.types.GetIamPolicyRequest
+ isExternal: false
+ name: GetIamPolicyRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.GetIamPolicyRequest
+- fullName: google.cloud.pubsub_v1.types.GetSnapshotRequest
+ isExternal: false
+ name: GetSnapshotRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.GetSnapshotRequest
+- fullName: google.cloud.pubsub_v1.types.GetSubscriptionRequest
+ isExternal: false
+ name: GetSubscriptionRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.GetSubscriptionRequest
+- fullName: google.cloud.pubsub_v1.types.GetTopicRequest
+ isExternal: false
+ name: GetTopicRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.GetTopicRequest
+- fullName: google.cloud.pubsub_v1.types.Http
+ isExternal: false
+ name: Http
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Http
+- fullName: google.cloud.pubsub_v1.types.HttpRule
+ isExternal: false
+ name: HttpRule
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.HttpRule
+- fullName: google.cloud.pubsub_v1.types.LimitExceededBehavior
+ isExternal: false
+ name: LimitExceededBehavior
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.LimitExceededBehavior
+- fullName: google.cloud.pubsub_v1.types.ListSnapshotsRequest
+ isExternal: false
+ name: ListSnapshotsRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListSnapshotsRequest
+- fullName: google.cloud.pubsub_v1.types.ListSnapshotsResponse
+ isExternal: false
+ name: ListSnapshotsResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListSnapshotsResponse
+- fullName: google.cloud.pubsub_v1.types.ListSubscriptionsRequest
+ isExternal: false
+ name: ListSubscriptionsRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListSubscriptionsRequest
+- fullName: google.cloud.pubsub_v1.types.ListSubscriptionsResponse
+ isExternal: false
+ name: ListSubscriptionsResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListSubscriptionsResponse
+- fullName: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest
+ isExternal: false
+ name: ListTopicSnapshotsRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest
+- fullName: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse
+ isExternal: false
+ name: ListTopicSnapshotsResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse
+- fullName: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest
+ isExternal: false
+ name: ListTopicSubscriptionsRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest
+- fullName: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse
+ isExternal: false
+ name: ListTopicSubscriptionsResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse
+- fullName: google.cloud.pubsub_v1.types.ListTopicsRequest
+ isExternal: false
+ name: ListTopicsRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListTopicsRequest
+- fullName: google.cloud.pubsub_v1.types.ListTopicsResponse
+ isExternal: false
+ name: ListTopicsResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ListTopicsResponse
+- fullName: google.cloud.pubsub_v1.types.MessageOptions
+ isExternal: false
+ name: MessageOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.MessageOptions
+- fullName: google.cloud.pubsub_v1.types.MessageStoragePolicy
+ isExternal: false
+ name: MessageStoragePolicy
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.MessageStoragePolicy
+- fullName: google.cloud.pubsub_v1.types.MethodDescriptorProto
+ isExternal: false
+ name: MethodDescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.MethodDescriptorProto
+- fullName: google.cloud.pubsub_v1.types.MethodOptions
+ isExternal: false
+ name: MethodOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.MethodOptions
+- fullName: google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest
+ isExternal: false
+ name: ModifyAckDeadlineRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest
+- fullName: google.cloud.pubsub_v1.types.ModifyPushConfigRequest
+ isExternal: false
+ name: ModifyPushConfigRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ModifyPushConfigRequest
+- fullName: google.cloud.pubsub_v1.types.OneofDescriptorProto
+ isExternal: false
+ name: OneofDescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.OneofDescriptorProto
+- fullName: google.cloud.pubsub_v1.types.OneofOptions
+ isExternal: false
+ name: OneofOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.OneofOptions
+- fullName: google.cloud.pubsub_v1.types.Policy
+ isExternal: false
+ name: Policy
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Policy
+- fullName: google.cloud.pubsub_v1.types.PolicyDelta
+ isExternal: false
+ name: PolicyDelta
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PolicyDelta
+- fullName: google.cloud.pubsub_v1.types.PublishFlowControl
+ isExternal: false
+ name: PublishFlowControl
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl
+- fullName: google.cloud.pubsub_v1.types.PublishRequest
+ isExternal: false
+ name: PublishRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PublishRequest
+- fullName: google.cloud.pubsub_v1.types.PublishResponse
+ isExternal: false
+ name: PublishResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PublishResponse
+- fullName: google.cloud.pubsub_v1.types.PublisherOptions
+ isExternal: false
+ name: PublisherOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PublisherOptions
+- fullName: google.cloud.pubsub_v1.types.PubsubMessage
+ isExternal: false
+ name: PubsubMessage
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PubsubMessage
+- fullName: google.cloud.pubsub_v1.types.PullRequest
+ isExternal: false
+ name: PullRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PullRequest
+- fullName: google.cloud.pubsub_v1.types.PullResponse
+ isExternal: false
+ name: PullResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PullResponse
+- fullName: google.cloud.pubsub_v1.types.PushConfig
+ isExternal: false
+ name: PushConfig
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.PushConfig
+- fullName: google.cloud.pubsub_v1.types.ReceivedMessage
+ isExternal: false
+ name: ReceivedMessage
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ReceivedMessage
+- fullName: google.cloud.pubsub_v1.types.RetryPolicy
+ isExternal: false
+ name: RetryPolicy
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.RetryPolicy
+- fullName: google.cloud.pubsub_v1.types.SchemaSettings
+ isExternal: false
+ name: SchemaSettings
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.SchemaSettings
+- fullName: google.cloud.pubsub_v1.types.SeekRequest
+ isExternal: false
+ name: SeekRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.SeekRequest
+- fullName: google.cloud.pubsub_v1.types.SeekResponse
+ isExternal: false
+ name: SeekResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.SeekResponse
+- fullName: google.cloud.pubsub_v1.types.ServiceDescriptorProto
+ isExternal: false
+ name: ServiceDescriptorProto
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ServiceDescriptorProto
+- fullName: google.cloud.pubsub_v1.types.ServiceOptions
+ isExternal: false
+ name: ServiceOptions
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.ServiceOptions
+- fullName: google.cloud.pubsub_v1.types.SetIamPolicyRequest
+ isExternal: false
+ name: SetIamPolicyRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.SetIamPolicyRequest
+- fullName: google.cloud.pubsub_v1.types.Snapshot
+ isExternal: false
+ name: Snapshot
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Snapshot
+- fullName: google.cloud.pubsub_v1.types.SourceCodeInfo
+ isExternal: false
+ name: SourceCodeInfo
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.SourceCodeInfo
+- fullName: google.cloud.pubsub_v1.types.StreamingPullRequest
+ isExternal: false
+ name: StreamingPullRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.StreamingPullRequest
+- fullName: google.cloud.pubsub_v1.types.StreamingPullResponse
+ isExternal: false
+ name: StreamingPullResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse
+- fullName: google.cloud.pubsub_v1.types.Subscription
+ isExternal: false
+ name: Subscription
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Subscription
+- fullName: google.cloud.pubsub_v1.types.TestIamPermissionsRequest
+ isExternal: false
+ name: TestIamPermissionsRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.TestIamPermissionsRequest
+- fullName: google.cloud.pubsub_v1.types.TestIamPermissionsResponse
+ isExternal: false
+ name: TestIamPermissionsResponse
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.TestIamPermissionsResponse
+- fullName: google.cloud.pubsub_v1.types.Timestamp
+ isExternal: false
+ name: Timestamp
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Timestamp
+- fullName: google.cloud.pubsub_v1.types.Topic
+ isExternal: false
+ name: Topic
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.Topic
+- fullName: google.cloud.pubsub_v1.types.UninterpretedOption
+ isExternal: false
+ name: UninterpretedOption
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.UninterpretedOption
+- fullName: google.cloud.pubsub_v1.types.UpdateSnapshotRequest
+ isExternal: false
+ name: UpdateSnapshotRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.UpdateSnapshotRequest
+- fullName: google.cloud.pubsub_v1.types.UpdateSubscriptionRequest
+ isExternal: false
+ name: UpdateSubscriptionRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.UpdateSubscriptionRequest
+- fullName: google.cloud.pubsub_v1.types.UpdateTopicRequest
+ isExternal: false
+ name: UpdateTopicRequest
+ parent: google.cloud.pubsub_v1.types
+ uid: google.cloud.pubsub_v1.types.UpdateTopicRequest
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager.yml
new file mode 100644
index 000000000000..e008869f3d03
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager.yml
@@ -0,0 +1,96 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSnapshotsAsyncPager
+ source:
+ id: ListTopicSnapshotsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 348
+ summary: 'A pager for iterating through `list_topic_snapshots` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListTopicSnapshotsResponse` object, and
+
+ provides an `__aiter__` method to iterate through its
+
+ `snapshots` field.
+
+
+ If there are more pages, the `__aiter__` method will make additional
+
+ `ListTopicSnapshots` requests and continue to iterate
+
+ through the `snapshots` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListTopicSnapshotsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListTopicSnapshotsAsyncPager(\n method: typing.Callable[\n \
+ \ [...], typing.Awaitable[google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse]\n\
+ \ ],\n request: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse,\n \
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+- attributes: []
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSnapshotsAsyncPager
+ source:
+ id: ListTopicSnapshotsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 348
+ summary: 'Instantiates the pager.
+
+ '
+ syntax:
+ content: "ListTopicSnapshotsAsyncPager(\n method: typing.Callable[\n \
+ \ [...], typing.Awaitable[google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse]\n\
+ \ ],\n request: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse,\n \
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListTopicSnapshotsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListTopicSnapshotsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+references:
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ isExternal: false
+ name: ListTopicSnapshotsAsyncPager
+ parent: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager.yml
new file mode 100644
index 000000000000..579fc1a35248
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager.yml
@@ -0,0 +1,94 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSnapshotsPager
+ source:
+ id: ListTopicSnapshotsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 286
+ summary: 'A pager for iterating through `list_topic_snapshots` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListTopicSnapshotsResponse` object, and
+
+ provides an `__iter__` method to iterate through its
+
+ `snapshots` field.
+
+
+ If there are more pages, the `__iter__` method will make additional
+
+ `ListTopicSnapshots` requests and continue to iterate
+
+ through the `snapshots` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListTopicSnapshotsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListTopicSnapshotsPager(\n method: typing.Callable[\n [...],\
+ \ google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse\n ],\n request:\
+ \ google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest,\n response: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+- attributes: []
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSnapshotsPager
+ source:
+ id: ListTopicSnapshotsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 286
+ summary: 'Instantiate the pager.
+
+ '
+ syntax:
+ content: "ListTopicSnapshotsPager(\n method: typing.Callable[\n [...],\
+ \ google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse\n ],\n request:\
+ \ google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest,\n response: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListTopicSnapshotsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListTopicSnapshotsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+references:
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ isExternal: false
+ name: ListTopicSnapshotsPager
+ parent: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager.yml
new file mode 100644
index 000000000000..b6f00c53db83
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager.yml
@@ -0,0 +1,96 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSubscriptionsAsyncPager
+ source:
+ id: ListTopicSubscriptionsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 220
+ summary: 'A pager for iterating through `list_topic_subscriptions` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListTopicSubscriptionsResponse` object, and
+
+ provides an `__aiter__` method to iterate through its
+
+ `subscriptions` field.
+
+
+ If there are more pages, the `__aiter__` method will make additional
+
+ `ListTopicSubscriptions` requests and continue to iterate
+
+ through the `subscriptions` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListTopicSubscriptionsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListTopicSubscriptionsAsyncPager(\n method: typing.Callable[\n \
+ \ [...],\n typing.Awaitable[google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse],\n\
+ \ ],\n request: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+- attributes: []
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSubscriptionsAsyncPager
+ source:
+ id: ListTopicSubscriptionsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 220
+ summary: 'Instantiates the pager.
+
+ '
+ syntax:
+ content: "ListTopicSubscriptionsAsyncPager(\n method: typing.Callable[\n \
+ \ [...],\n typing.Awaitable[google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse],\n\
+ \ ],\n request: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListTopicSubscriptionsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListTopicSubscriptionsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+references:
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ isExternal: false
+ name: ListTopicSubscriptionsAsyncPager
+ parent: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager.yml
new file mode 100644
index 000000000000..7941824e50b4
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager.yml
@@ -0,0 +1,96 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSubscriptionsPager
+ source:
+ id: ListTopicSubscriptionsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 158
+ summary: 'A pager for iterating through `list_topic_subscriptions` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListTopicSubscriptionsResponse` object, and
+
+ provides an `__iter__` method to iterate through its
+
+ `subscriptions` field.
+
+
+ If there are more pages, the `__iter__` method will make additional
+
+ `ListTopicSubscriptions` requests and continue to iterate
+
+ through the `subscriptions` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListTopicSubscriptionsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListTopicSubscriptionsPager(\n method: typing.Callable[\n \
+ \ [...], google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse\n ],\n\
+ \ request: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+- attributes: []
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicSubscriptionsPager
+ source:
+ id: ListTopicSubscriptionsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 158
+ summary: 'Instantiate the pager.
+
+ '
+ syntax:
+ content: "ListTopicSubscriptionsPager(\n method: typing.Callable[\n \
+ \ [...], google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse\n ],\n\
+ \ request: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListTopicSubscriptionsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListTopicSubscriptionsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+references:
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ isExternal: false
+ name: ListTopicSubscriptionsPager
+ parent: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager.yml
new file mode 100644
index 000000000000..5c59b2bdbb08
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager.yml
@@ -0,0 +1,96 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicsAsyncPager
+ source:
+ id: ListTopicsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 92
+ summary: 'A pager for iterating through `list_topics` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListTopicsResponse` object, and
+
+ provides an `__aiter__` method to iterate through its
+
+ `topics` field.
+
+
+ If there are more pages, the `__aiter__` method will make additional
+
+ `ListTopics` requests and continue to iterate
+
+ through the `topics` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListTopicsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListTopicsAsyncPager(\n method: typing.Callable[\n [...],\
+ \ typing.Awaitable[google.cloud.pubsub_v1.types.ListTopicsResponse]\n ],\n\
+ \ request: google.cloud.pubsub_v1.types.ListTopicsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListTopicsResponse,\n *,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+- attributes: []
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicsAsyncPager
+ source:
+ id: ListTopicsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 92
+ summary: 'Instantiates the pager.
+
+ '
+ syntax:
+ content: "ListTopicsAsyncPager(\n method: typing.Callable[\n [...],\
+ \ typing.Awaitable[google.cloud.pubsub_v1.types.ListTopicsResponse]\n ],\n\
+ \ request: google.cloud.pubsub_v1.types.ListTopicsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListTopicsResponse,\n *,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListTopicsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListTopicsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+references:
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ isExternal: false
+ name: ListTopicsAsyncPager
+ parent: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicsPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicsPager.yml
new file mode 100644
index 000000000000..5c4b69fdb2c1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.ListTopicsPager.yml
@@ -0,0 +1,94 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicsPager
+ source:
+ id: ListTopicsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 30
+ summary: 'A pager for iterating through `list_topics` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListTopicsResponse` object, and
+
+ provides an `__iter__` method to iterate through its
+
+ `topics` field.
+
+
+ If there are more pages, the `__iter__` method will make additional
+
+ `ListTopics` requests and continue to iterate
+
+ through the `topics` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListTopicsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListTopicsPager(\n method: typing.Callable[[...], google.cloud.pubsub_v1.types.ListTopicsResponse],\n\
+ \ request: google.cloud.pubsub_v1.types.ListTopicsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListTopicsResponse,\n *,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+- attributes: []
+ class: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: ListTopicsPager
+ source:
+ id: ListTopicsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 30
+ summary: 'Instantiate the pager.
+
+ '
+ syntax:
+ content: "ListTopicsPager(\n method: typing.Callable[[...], google.cloud.pubsub_v1.types.ListTopicsResponse],\n\
+ \ request: google.cloud.pubsub_v1.types.ListTopicsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListTopicsResponse,\n *,\n metadata: typing.Sequence[typing.Tuple[str,\
+ \ str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListTopicsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListTopicsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+references:
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ isExternal: false
+ name: ListTopicsPager
+ parent: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.yml
new file mode 100644
index 000000000000..9f129659c33e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.publisher.pagers.yml
@@ -0,0 +1,54 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ - google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ - google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ - google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ fullName: google.pubsub_v1.services.publisher.pagers
+ langs:
+ - python
+ module: google.pubsub_v1.services.publisher.pagers
+ name: publisher.pagers
+ source:
+ id: pagers
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/publisher/pagers.py
+ startLine: 0
+ summary: API documentation for `pubsub_v1.services.publisher.pagers` module.
+ syntax: {}
+ type: module
+ uid: google.pubsub_v1.services.publisher.pagers
+references:
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ isExternal: false
+ name: ListTopicSnapshotsAsyncPager
+ parent: google.pubsub_v1.services.publisher.pagers
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ isExternal: false
+ name: ListTopicSnapshotsPager
+ parent: google.pubsub_v1.services.publisher.pagers
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ isExternal: false
+ name: ListTopicSubscriptionsAsyncPager
+ parent: google.pubsub_v1.services.publisher.pagers
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ isExternal: false
+ name: ListTopicSubscriptionsPager
+ parent: google.pubsub_v1.services.publisher.pagers
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ isExternal: false
+ name: ListTopicsAsyncPager
+ parent: google.pubsub_v1.services.publisher.pagers
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+- fullName: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ isExternal: false
+ name: ListTopicsPager
+ parent: google.pubsub_v1.services.publisher.pagers
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager.yml
new file mode 100644
index 000000000000..e19f90d0caa9
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager.yml
@@ -0,0 +1,96 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ class: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSnapshotsAsyncPager
+ source:
+ id: ListSnapshotsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 220
+ summary: 'A pager for iterating through `list_snapshots` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListSnapshotsResponse` object, and
+
+ provides an `__aiter__` method to iterate through its
+
+ `snapshots` field.
+
+
+ If there are more pages, the `__aiter__` method will make additional
+
+ `ListSnapshots` requests and continue to iterate
+
+ through the `snapshots` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListSnapshotsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListSnapshotsAsyncPager(\n method: typing.Callable[\n [...],\
+ \ typing.Awaitable[google.cloud.pubsub_v1.types.ListSnapshotsResponse]\n \
+ \ ],\n request: google.cloud.pubsub_v1.types.ListSnapshotsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListSnapshotsResponse,\n *,\n metadata:\
+ \ typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+- attributes: []
+ class: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSnapshotsAsyncPager
+ source:
+ id: ListSnapshotsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 220
+ summary: 'Instantiates the pager.
+
+ '
+ syntax:
+ content: "ListSnapshotsAsyncPager(\n method: typing.Callable[\n [...],\
+ \ typing.Awaitable[google.cloud.pubsub_v1.types.ListSnapshotsResponse]\n \
+ \ ],\n request: google.cloud.pubsub_v1.types.ListSnapshotsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListSnapshotsResponse,\n *,\n metadata:\
+ \ typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListSnapshotsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListSnapshotsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+references:
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ isExternal: false
+ name: ListSnapshotsAsyncPager
+ parent: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager.yml
new file mode 100644
index 000000000000..9dec2d2a0019
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager.yml
@@ -0,0 +1,94 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ class: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSnapshotsPager
+ source:
+ id: ListSnapshotsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 158
+ summary: 'A pager for iterating through `list_snapshots` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListSnapshotsResponse` object, and
+
+ provides an `__iter__` method to iterate through its
+
+ `snapshots` field.
+
+
+ If there are more pages, the `__iter__` method will make additional
+
+ `ListSnapshots` requests and continue to iterate
+
+ through the `snapshots` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListSnapshotsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListSnapshotsPager(\n method: typing.Callable[[...], google.cloud.pubsub_v1.types.ListSnapshotsResponse],\n\
+ \ request: google.cloud.pubsub_v1.types.ListSnapshotsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListSnapshotsResponse,\n *,\n metadata:\
+ \ typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+- attributes: []
+ class: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSnapshotsPager
+ source:
+ id: ListSnapshotsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 158
+ summary: 'Instantiate the pager.
+
+ '
+ syntax:
+ content: "ListSnapshotsPager(\n method: typing.Callable[[...], google.cloud.pubsub_v1.types.ListSnapshotsResponse],\n\
+ \ request: google.cloud.pubsub_v1.types.ListSnapshotsRequest,\n response:\
+ \ google.cloud.pubsub_v1.types.ListSnapshotsResponse,\n *,\n metadata:\
+ \ typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListSnapshotsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListSnapshotsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+references:
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ isExternal: false
+ name: ListSnapshotsPager
+ parent: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager.yml
new file mode 100644
index 000000000000..e3e1e2db5108
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager.yml
@@ -0,0 +1,96 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ class: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSubscriptionsAsyncPager
+ source:
+ id: ListSubscriptionsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 92
+ summary: 'A pager for iterating through `list_subscriptions` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListSubscriptionsResponse` object, and
+
+ provides an `__aiter__` method to iterate through its
+
+ `subscriptions` field.
+
+
+ If there are more pages, the `__aiter__` method will make additional
+
+ `ListSubscriptions` requests and continue to iterate
+
+ through the `subscriptions` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListSubscriptionsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListSubscriptionsAsyncPager(\n method: typing.Callable[\n \
+ \ [...], typing.Awaitable[google.cloud.pubsub_v1.types.ListSubscriptionsResponse]\n\
+ \ ],\n request: google.cloud.pubsub_v1.types.ListSubscriptionsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListSubscriptionsResponse,\n \
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+- attributes: []
+ class: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSubscriptionsAsyncPager
+ source:
+ id: ListSubscriptionsAsyncPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 92
+ summary: 'Instantiates the pager.
+
+ '
+ syntax:
+ content: "ListSubscriptionsAsyncPager(\n method: typing.Callable[\n \
+ \ [...], typing.Awaitable[google.cloud.pubsub_v1.types.ListSubscriptionsResponse]\n\
+ \ ],\n request: google.cloud.pubsub_v1.types.ListSubscriptionsRequest,\n\
+ \ response: google.cloud.pubsub_v1.types.ListSubscriptionsResponse,\n \
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListSubscriptionsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListSubscriptionsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+references:
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ isExternal: false
+ name: ListSubscriptionsAsyncPager
+ parent: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager.yml
new file mode 100644
index 000000000000..4a9edc3f043b
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager.yml
@@ -0,0 +1,94 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- attributes: []
+ children:
+ - google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ class: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSubscriptionsPager
+ source:
+ id: ListSubscriptionsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 30
+ summary: 'A pager for iterating through `list_subscriptions` requests.
+
+
+ This class thinly wraps an initial
+
+ `google.pubsub_v1.types.ListSubscriptionsResponse` object, and
+
+ provides an `__iter__` method to iterate through its
+
+ `subscriptions` field.
+
+
+ If there are more pages, the `__iter__` method will make additional
+
+ `ListSubscriptions` requests and continue to iterate
+
+ through the `subscriptions` field on the
+
+ corresponding responses.
+
+
+ All the usual `google.pubsub_v1.types.ListSubscriptionsResponse`
+
+ attributes are available on the pager. If multiple requests are made, only
+
+ the most recent response is retained, and thus used for attribute lookup.
+
+
+ '
+ syntax:
+ content: "ListSubscriptionsPager(\n method: typing.Callable[\n [...],\
+ \ google.cloud.pubsub_v1.types.ListSubscriptionsResponse\n ],\n request:\
+ \ google.cloud.pubsub_v1.types.ListSubscriptionsRequest,\n response: google.cloud.pubsub_v1.types.ListSubscriptionsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters: []
+ type: class
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+- attributes: []
+ class: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: ListSubscriptionsPager
+ source:
+ id: ListSubscriptionsPager
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 30
+ summary: 'Instantiate the pager.
+
+ '
+ syntax:
+ content: "ListSubscriptionsPager(\n method: typing.Callable[\n [...],\
+ \ google.cloud.pubsub_v1.types.ListSubscriptionsResponse\n ],\n request:\
+ \ google.cloud.pubsub_v1.types.ListSubscriptionsRequest,\n response: google.cloud.pubsub_v1.types.ListSubscriptionsResponse,\n\
+ \ *,\n metadata: typing.Sequence[typing.Tuple[str, str]] = ()\n)"
+ parameters:
+ - description: The method that was originally called, and which instantiated this
+ pager.
+ id: method
+ var_type: Callable
+ - description: The initial request object.
+ id: request
+ var_type: google.pubsub_v1.types.ListSubscriptionsRequest
+ - description: The initial response object.
+ id: response
+ var_type: google.pubsub_v1.types.ListSubscriptionsResponse
+ - description: Strings which should be sent along with the request as metadata.
+ id: metadata
+ var_type: Sequence[Tuple[str, str]]
+ type: method
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+references:
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ isExternal: false
+ name: ListSubscriptionsPager
+ parent: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.yml
new file mode 100644
index 000000000000..100c9943377e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/google.pubsub_v1.services.subscriber.pagers.yml
@@ -0,0 +1,42 @@
+### YamlMime:UniversalReference
+api_name: []
+items:
+- children:
+ - google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ - google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ - google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ - google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ fullName: google.pubsub_v1.services.subscriber.pagers
+ langs:
+ - python
+ module: google.pubsub_v1.services.subscriber.pagers
+ name: subscriber.pagers
+ source:
+ id: pagers
+ path: tests/testdata/gapic-combo/google/pubsub_v1/services/subscriber/pagers.py
+ startLine: 0
+ summary: API documentation for `pubsub_v1.services.subscriber.pagers` module.
+ syntax: {}
+ type: module
+ uid: google.pubsub_v1.services.subscriber.pagers
+references:
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ isExternal: false
+ name: ListSnapshotsAsyncPager
+ parent: google.pubsub_v1.services.subscriber.pagers
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ isExternal: false
+ name: ListSnapshotsPager
+ parent: google.pubsub_v1.services.subscriber.pagers
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ isExternal: false
+ name: ListSubscriptionsAsyncPager
+ parent: google.pubsub_v1.services.subscriber.pagers
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+- fullName: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ isExternal: false
+ name: ListSubscriptionsPager
+ parent: google.pubsub_v1.services.subscriber.pagers
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/index.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/index.md
new file mode 100644
index 000000000000..51b5509c7c61
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/index.md
@@ -0,0 +1,189 @@
+# Python Client for Google Cloud Pub / Sub
+
+[](https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability) [](https://pypi.org/project/google-cloud-pubsub/) [](https://pypi.org/project/google-cloud-pubsub/)
+
+[Google Cloud Pub / Sub](https://cloud.google.com/pubsub/) is a fully-managed real-time messaging service that
+allows you to send and receive messages between independent applications. You
+can leverage Cloud Pub/Sub’s flexibility to decouple systems and components
+hosted on Google Cloud Platform or elsewhere on the Internet. By building on
+the same technology Google uses, Cloud Pub / Sub is designed to provide “at
+least once” delivery at low latency with on-demand scalability to 1 million
+messages per second (and beyond).
+
+Publisher applications can send messages to a `topic` and other applications
+can subscribe to that topic to receive the messages. By decoupling senders and
+receivers, Google Cloud Pub/Sub allows developers to communicate between
+independently written applications.
+
+
+* [Product Documentation](https://cloud.google.com/pubsub/docs)
+
+
+* [Client Library Documentation](https://cloud.google.com/python/docs/reference/pubsub/latest)
+
+## Quick Start
+
+In order to use this library, you first need to go through the following steps:
+
+
+1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+
+
+2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+
+
+3. [Enable the Google Cloud Pub / Sub API.](https://cloud.google.com/pubsub)
+
+
+4. [Setup Authentication.](https://googleapis.dev/python/google-api-core/latest/auth.html)
+
+### Installation
+
+Install this library in a [virtualenv](https://virtualenv.pypa.io/en/latest/) using pip. [virtualenv](https://virtualenv.pypa.io/en/latest/) is a tool to
+create isolated Python environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
+
+With [virtualenv](https://virtualenv.pypa.io/en/latest/), it’s possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
+
+#### Supported Python Versions
+
+Python >= 3.7
+
+#### Deprecated Python Versions
+
+Python <= 3.6.
+
+The last version of this library compatible with Python 2.7 is google-cloud-pubsub==1.7.0.
+
+#### Mac/Linux
+
+```console
+pip install virtualenv
+virtualenv
+source /bin/activate
+/bin/pip install google-cloud-pubsub
+```
+
+#### Windows
+
+```console
+pip install virtualenv
+virtualenv
+\Scripts\activate
+\Scripts\pip.exe install google-cloud-pubsub
+```
+
+### Example Usage
+
+#### Publishing
+
+To publish data to Cloud Pub/Sub you must create a topic, and then publish
+messages to it
+
+```python
+import os
+from google.cloud import pubsub_v1
+
+publisher = pubsub_v1.PublisherClient()
+topic_name = 'projects/{project_id}/topics/{topic}'.format(
+ project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
+ topic='MY_TOPIC_NAME', # Set this to something appropriate.
+)
+publisher.create_topic(name=topic_name)
+future = publisher.publish(topic_name, b'My first message!', spam='eggs')
+future.result()
+```
+
+To learn more, consult the [publishing documentation](https://cloud.google.com/python/docs/reference/pubsub/latest).
+
+#### Subscribing
+
+To subscribe to data in Cloud Pub/Sub, you create a subscription based on
+the topic, and subscribe to that, passing a callback function.
+
+```python
+import os
+from google.cloud import pubsub_v1
+
+topic_name = 'projects/{project_id}/topics/{topic}'.format(
+ project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
+ topic='MY_TOPIC_NAME', # Set this to something appropriate.
+)
+
+subscription_name = 'projects/{project_id}/subscriptions/{sub}'.format(
+ project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
+ sub='MY_SUBSCRIPTION_NAME', # Set this to something appropriate.
+)
+
+def callback(message):
+ print(message.data)
+ message.ack()
+
+with pubsub_v1.SubscriberClient() as subscriber:
+ subscriber.create_subscription(
+ name=subscription_name, topic=topic_name)
+ future = subscriber.subscribe(subscription_name, callback)
+```
+
+The future returned by the call to `subscriber.subscribe` can be used to
+block the current thread until a given condition obtains:
+
+```python
+try:
+ future.result()
+except KeyboardInterrupt:
+ future.cancel()
+```
+
+It is also possible to pull messages in a synchronous (blocking) fashion. To
+learn more about subscribing, consult the [subscriber documentation](https://cloud.google.com/python/docs/reference/pubsub/latest).
+
+#### Authentication
+
+It is possible to specify the authentication method to use with the Pub/Sub
+clients. This can be done by providing an explicit [Credentials](https://google-auth.readthedocs.io/en/latest/reference/google.auth.credentials.html#google.auth.credentials.Credentials) instance. Support
+for various authentication methods is available from the [google-auth](https://google-auth.readthedocs.io/en/latest/index.html) library.
+
+For example, to use JSON Web Tokens, provide a [google.auth.jwt.Credentials](https://google-auth.readthedocs.io/en/latest/reference/google.auth.jwt.html#google.auth.jwt.Credentials) instance:
+
+```python
+import json
+from google.auth import jwt
+
+service_account_info = json.load(open("service-account-info.json"))
+audience = "https://pubsub.googleapis.com/google.pubsub.v1.Subscriber"
+
+credentials = jwt.Credentials.from_service_account_info(
+ service_account_info, audience=audience
+)
+
+subscriber = pubsub_v1.SubscriberClient(credentials=credentials)
+
+# The same for the publisher, except that the "audience" claim needs to be adjusted
+publisher_audience = "https://pubsub.googleapis.com/google.pubsub.v1.Publisher"
+credentials_pub = credentials.with_claims(audience=publisher_audience)
+publisher = pubsub_v1.PublisherClient(credentials=credentials_pub)
+```
+
+## Versioning
+
+This library follows [Semantic Versioning](http://semver.org/).
+
+It is currently in major version one (1.y.z), which means that the public API should be considered stable.
+
+## Contributing
+
+Contributions to this library are always welcome and highly encouraged.
+
+See the [CONTRIBUTING doc](https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst) for more information on how to get started.
+
+## Community
+
+Google Cloud Platform Python developers hang out in [Slack](https://googlecloud-community.slack.com) in the `#python`
+channel, click here to [get an invitation](https://gcp-slack.appspot.com/).
+
+## License
+
+Apache 2.0 - See [the LICENSE](https://github.com/googleapis/google-cloud-python/blob/main/LICENSE) for more information.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/multiprocessing.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/multiprocessing.md
new file mode 100644
index 000000000000..ac442c0c7185
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/multiprocessing.md
@@ -0,0 +1,7 @@
+# Multiprocessing
+
+**NOTE**: Because this client uses [`grpc`](https://grpc.github.io/grpc/python/grpc.html#module-grpc) library, it is safe to
+share instances across threads. In multiprocessing scenarios, the best
+practice is to create client instances *after* the invocation of
+[`os.fork()`](https://python.readthedocs.io/en/latest/library/os.html#os.fork) by [`multiprocessing.pool.Pool`](https://python.readthedocs.io/en/latest/library/multiprocessing.html#multiprocessing.pool.Pool) or
+[`multiprocessing.Process`](https://python.readthedocs.io/en/latest/library/multiprocessing.html#multiprocessing.Process).
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/toc.yml b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/toc.yml
new file mode 100644
index 000000000000..8b91b0cc1f64
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/toc.yml
@@ -0,0 +1,364 @@
+- items:
+ - href: index.md
+ name: Overview
+ - href: changelog.md
+ name: Changelog
+ - href: multiprocessing.md
+ name: Multiprocessing
+ - href: upgrading.md
+ name: 2.0.0 Migration Guide
+ - items:
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.publisher.client
+ - name: Client
+ uid: google.cloud.pubsub_v1.publisher.client.Client
+ name: publisher.client
+ uid: google.cloud.pubsub_v1.publisher.client
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.publisher.futures
+ - name: Future
+ uid: google.cloud.pubsub_v1.publisher.futures.Future
+ name: publisher.futures
+ uid: google.cloud.pubsub_v1.publisher.futures
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.subscriber.client
+ - name: Client
+ uid: google.cloud.pubsub_v1.subscriber.client.Client
+ name: subscriber.client
+ uid: google.cloud.pubsub_v1.subscriber.client
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.subscriber.futures
+ - name: Future
+ uid: google.cloud.pubsub_v1.subscriber.futures.Future
+ - name: StreamingPullFuture
+ uid: google.cloud.pubsub_v1.subscriber.futures.StreamingPullFuture
+ name: subscriber.futures
+ uid: google.cloud.pubsub_v1.subscriber.futures
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.subscriber.scheduler
+ - name: Scheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.Scheduler
+ - name: ThreadScheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler.ThreadScheduler
+ name: scheduler
+ uid: google.cloud.pubsub_v1.subscriber.scheduler
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types
+ - name: AcknowledgeRequest
+ uid: google.cloud.pubsub_v1.types.AcknowledgeRequest
+ - name: AuditConfig
+ uid: google.cloud.pubsub_v1.types.AuditConfig
+ - name: AuditConfigDelta
+ uid: google.cloud.pubsub_v1.types.AuditConfigDelta
+ - name: AuditData
+ uid: google.cloud.pubsub_v1.types.AuditData
+ - name: AuditLogConfig
+ uid: google.cloud.pubsub_v1.types.AuditLogConfig
+ - name: BatchSettings
+ uid: google.cloud.pubsub_v1.types.BatchSettings
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.BigQueryConfig
+ - name: State
+ uid: google.cloud.pubsub_v1.types.BigQueryConfig.State
+ name: BigQueryConfig
+ uid: google.cloud.pubsub_v1.types.BigQueryConfig
+ - name: Binding
+ uid: google.cloud.pubsub_v1.types.Binding
+ - name: BindingDelta
+ uid: google.cloud.pubsub_v1.types.BindingDelta
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ - name: LabelsEntry
+ uid: google.cloud.pubsub_v1.types.CreateSnapshotRequest.LabelsEntry
+ name: CreateSnapshotRequest
+ uid: google.cloud.pubsub_v1.types.CreateSnapshotRequest
+ - name: CustomHttpPattern
+ uid: google.cloud.pubsub_v1.types.CustomHttpPattern
+ - name: DeadLetterPolicy
+ uid: google.cloud.pubsub_v1.types.DeadLetterPolicy
+ - name: DeleteSnapshotRequest
+ uid: google.cloud.pubsub_v1.types.DeleteSnapshotRequest
+ - name: DeleteSubscriptionRequest
+ uid: google.cloud.pubsub_v1.types.DeleteSubscriptionRequest
+ - name: DeleteTopicRequest
+ uid: google.cloud.pubsub_v1.types.DeleteTopicRequest
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.DescriptorProto
+ - name: ExtensionRange
+ uid: google.cloud.pubsub_v1.types.DescriptorProto.ExtensionRange
+ - name: ReservedRange
+ uid: google.cloud.pubsub_v1.types.DescriptorProto.ReservedRange
+ name: DescriptorProto
+ uid: google.cloud.pubsub_v1.types.DescriptorProto
+ - name: DetachSubscriptionRequest
+ uid: google.cloud.pubsub_v1.types.DetachSubscriptionRequest
+ - name: DetachSubscriptionResponse
+ uid: google.cloud.pubsub_v1.types.DetachSubscriptionResponse
+ - name: Duration
+ uid: google.cloud.pubsub_v1.types.Duration
+ - name: Empty
+ uid: google.cloud.pubsub_v1.types.Empty
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.EnumDescriptorProto
+ - name: EnumReservedRange
+ uid: google.cloud.pubsub_v1.types.EnumDescriptorProto.EnumReservedRange
+ name: EnumDescriptorProto
+ uid: google.cloud.pubsub_v1.types.EnumDescriptorProto
+ - name: EnumOptions
+ uid: google.cloud.pubsub_v1.types.EnumOptions
+ - name: EnumValueDescriptorProto
+ uid: google.cloud.pubsub_v1.types.EnumValueDescriptorProto
+ - name: EnumValueOptions
+ uid: google.cloud.pubsub_v1.types.EnumValueOptions
+ - name: ExpirationPolicy
+ uid: google.cloud.pubsub_v1.types.ExpirationPolicy
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ - name: Declaration
+ uid: google.cloud.pubsub_v1.types.ExtensionRangeOptions.Declaration
+ name: ExtensionRangeOptions
+ uid: google.cloud.pubsub_v1.types.ExtensionRangeOptions
+ - name: FeatureSet
+ uid: google.cloud.pubsub_v1.types.FeatureSet
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.FeatureSetDefaults
+ - name: FeatureSetEditionDefault
+ uid: google.cloud.pubsub_v1.types.FeatureSetDefaults.FeatureSetEditionDefault
+ name: FeatureSetDefaults
+ uid: google.cloud.pubsub_v1.types.FeatureSetDefaults
+ - name: FieldDescriptorProto
+ uid: google.cloud.pubsub_v1.types.FieldDescriptorProto
+ - name: FieldMask
+ uid: google.cloud.pubsub_v1.types.FieldMask
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.FieldOptions
+ - name: EditionDefault
+ uid: google.cloud.pubsub_v1.types.FieldOptions.EditionDefault
+ name: FieldOptions
+ uid: google.cloud.pubsub_v1.types.FieldOptions
+ - name: FileDescriptorProto
+ uid: google.cloud.pubsub_v1.types.FileDescriptorProto
+ - name: FileDescriptorSet
+ uid: google.cloud.pubsub_v1.types.FileDescriptorSet
+ - name: FileOptions
+ uid: google.cloud.pubsub_v1.types.FileOptions
+ - name: FlowControl
+ uid: google.cloud.pubsub_v1.types.FlowControl
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ - name: Annotation
+ uid: google.cloud.pubsub_v1.types.GeneratedCodeInfo.Annotation
+ name: GeneratedCodeInfo
+ uid: google.cloud.pubsub_v1.types.GeneratedCodeInfo
+ - name: GetIamPolicyRequest
+ uid: google.cloud.pubsub_v1.types.GetIamPolicyRequest
+ - name: GetSnapshotRequest
+ uid: google.cloud.pubsub_v1.types.GetSnapshotRequest
+ - name: GetSubscriptionRequest
+ uid: google.cloud.pubsub_v1.types.GetSubscriptionRequest
+ - name: GetTopicRequest
+ uid: google.cloud.pubsub_v1.types.GetTopicRequest
+ - name: Http
+ uid: google.cloud.pubsub_v1.types.Http
+ - name: HttpRule
+ uid: google.cloud.pubsub_v1.types.HttpRule
+ - name: LimitExceededBehavior
+ uid: google.cloud.pubsub_v1.types.LimitExceededBehavior
+ - name: ListSnapshotsRequest
+ uid: google.cloud.pubsub_v1.types.ListSnapshotsRequest
+ - name: ListSnapshotsResponse
+ uid: google.cloud.pubsub_v1.types.ListSnapshotsResponse
+ - name: ListSubscriptionsRequest
+ uid: google.cloud.pubsub_v1.types.ListSubscriptionsRequest
+ - name: ListSubscriptionsResponse
+ uid: google.cloud.pubsub_v1.types.ListSubscriptionsResponse
+ - name: ListTopicSnapshotsRequest
+ uid: google.cloud.pubsub_v1.types.ListTopicSnapshotsRequest
+ - name: ListTopicSnapshotsResponse
+ uid: google.cloud.pubsub_v1.types.ListTopicSnapshotsResponse
+ - name: ListTopicSubscriptionsRequest
+ uid: google.cloud.pubsub_v1.types.ListTopicSubscriptionsRequest
+ - name: ListTopicSubscriptionsResponse
+ uid: google.cloud.pubsub_v1.types.ListTopicSubscriptionsResponse
+ - name: ListTopicsRequest
+ uid: google.cloud.pubsub_v1.types.ListTopicsRequest
+ - name: ListTopicsResponse
+ uid: google.cloud.pubsub_v1.types.ListTopicsResponse
+ - name: MessageOptions
+ uid: google.cloud.pubsub_v1.types.MessageOptions
+ - name: MessageStoragePolicy
+ uid: google.cloud.pubsub_v1.types.MessageStoragePolicy
+ - name: MethodDescriptorProto
+ uid: google.cloud.pubsub_v1.types.MethodDescriptorProto
+ - name: MethodOptions
+ uid: google.cloud.pubsub_v1.types.MethodOptions
+ - name: ModifyAckDeadlineRequest
+ uid: google.cloud.pubsub_v1.types.ModifyAckDeadlineRequest
+ - name: ModifyPushConfigRequest
+ uid: google.cloud.pubsub_v1.types.ModifyPushConfigRequest
+ - name: OneofDescriptorProto
+ uid: google.cloud.pubsub_v1.types.OneofDescriptorProto
+ - name: OneofOptions
+ uid: google.cloud.pubsub_v1.types.OneofOptions
+ - name: Policy
+ uid: google.cloud.pubsub_v1.types.Policy
+ - name: PolicyDelta
+ uid: google.cloud.pubsub_v1.types.PolicyDelta
+ - name: PublishFlowControl
+ uid: google.cloud.pubsub_v1.types.PublishFlowControl
+ - name: PublishRequest
+ uid: google.cloud.pubsub_v1.types.PublishRequest
+ - name: PublishResponse
+ uid: google.cloud.pubsub_v1.types.PublishResponse
+ - name: PublisherOptions
+ uid: google.cloud.pubsub_v1.types.PublisherOptions
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.PubsubMessage
+ - name: AttributesEntry
+ uid: google.cloud.pubsub_v1.types.PubsubMessage.AttributesEntry
+ name: PubsubMessage
+ uid: google.cloud.pubsub_v1.types.PubsubMessage
+ - name: PullRequest
+ uid: google.cloud.pubsub_v1.types.PullRequest
+ - name: PullResponse
+ uid: google.cloud.pubsub_v1.types.PullResponse
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.PushConfig
+ - name: AttributesEntry
+ uid: google.cloud.pubsub_v1.types.PushConfig.AttributesEntry
+ - name: OidcToken
+ uid: google.cloud.pubsub_v1.types.PushConfig.OidcToken
+ name: PushConfig
+ uid: google.cloud.pubsub_v1.types.PushConfig
+ - name: ReceivedMessage
+ uid: google.cloud.pubsub_v1.types.ReceivedMessage
+ - name: RetryPolicy
+ uid: google.cloud.pubsub_v1.types.RetryPolicy
+ - name: SchemaSettings
+ uid: google.cloud.pubsub_v1.types.SchemaSettings
+ - name: SeekRequest
+ uid: google.cloud.pubsub_v1.types.SeekRequest
+ - name: SeekResponse
+ uid: google.cloud.pubsub_v1.types.SeekResponse
+ - name: ServiceDescriptorProto
+ uid: google.cloud.pubsub_v1.types.ServiceDescriptorProto
+ - name: ServiceOptions
+ uid: google.cloud.pubsub_v1.types.ServiceOptions
+ - name: SetIamPolicyRequest
+ uid: google.cloud.pubsub_v1.types.SetIamPolicyRequest
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.Snapshot
+ - name: LabelsEntry
+ uid: google.cloud.pubsub_v1.types.Snapshot.LabelsEntry
+ name: Snapshot
+ uid: google.cloud.pubsub_v1.types.Snapshot
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.SourceCodeInfo
+ - name: Location
+ uid: google.cloud.pubsub_v1.types.SourceCodeInfo.Location
+ name: SourceCodeInfo
+ uid: google.cloud.pubsub_v1.types.SourceCodeInfo
+ - name: StreamingPullRequest
+ uid: google.cloud.pubsub_v1.types.StreamingPullRequest
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse
+ - name: AcknowledgeConfirmation
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.AcknowledgeConfirmation
+ - name: ModifyAckDeadlineConfirmation
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.ModifyAckDeadlineConfirmation
+ - name: SubscriptionProperties
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse.SubscriptionProperties
+ name: StreamingPullResponse
+ uid: google.cloud.pubsub_v1.types.StreamingPullResponse
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.Subscription
+ - name: LabelsEntry
+ uid: google.cloud.pubsub_v1.types.Subscription.LabelsEntry
+ - name: State
+ uid: google.cloud.pubsub_v1.types.Subscription.State
+ name: Subscription
+ uid: google.cloud.pubsub_v1.types.Subscription
+ - name: TestIamPermissionsRequest
+ uid: google.cloud.pubsub_v1.types.TestIamPermissionsRequest
+ - name: TestIamPermissionsResponse
+ uid: google.cloud.pubsub_v1.types.TestIamPermissionsResponse
+ - name: Timestamp
+ uid: google.cloud.pubsub_v1.types.Timestamp
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.Topic
+ - name: LabelsEntry
+ uid: google.cloud.pubsub_v1.types.Topic.LabelsEntry
+ name: Topic
+ uid: google.cloud.pubsub_v1.types.Topic
+ - items:
+ - name: Overview
+ uid: google.cloud.pubsub_v1.types.UninterpretedOption
+ - name: NamePart
+ uid: google.cloud.pubsub_v1.types.UninterpretedOption.NamePart
+ name: UninterpretedOption
+ uid: google.cloud.pubsub_v1.types.UninterpretedOption
+ - name: UpdateSnapshotRequest
+ uid: google.cloud.pubsub_v1.types.UpdateSnapshotRequest
+ - name: UpdateSubscriptionRequest
+ uid: google.cloud.pubsub_v1.types.UpdateSubscriptionRequest
+ - name: UpdateTopicRequest
+ uid: google.cloud.pubsub_v1.types.UpdateTopicRequest
+ name: types
+ uid: google.cloud.pubsub_v1.types
+ - name: Message
+ uid: google.cloud.pubsub_v1.subscriber.message.Message
+ name: Pubsub V1
+ - items:
+ - items:
+ - name: Overview
+ uid: google.pubsub_v1.services.publisher.pagers
+ - name: ListTopicSnapshotsAsyncPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsAsyncPager
+ - name: ListTopicSnapshotsPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSnapshotsPager
+ - name: ListTopicSubscriptionsAsyncPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsAsyncPager
+ - name: ListTopicSubscriptionsPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicSubscriptionsPager
+ - name: ListTopicsAsyncPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsAsyncPager
+ - name: ListTopicsPager
+ uid: google.pubsub_v1.services.publisher.pagers.ListTopicsPager
+ name: publisher.pagers
+ uid: google.pubsub_v1.services.publisher.pagers
+ - items:
+ - name: Overview
+ uid: google.pubsub_v1.services.subscriber.pagers
+ - name: ListSnapshotsAsyncPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsAsyncPager
+ - name: ListSnapshotsPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSnapshotsPager
+ - name: ListSubscriptionsAsyncPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsAsyncPager
+ - name: ListSubscriptionsPager
+ uid: google.pubsub_v1.services.subscriber.pagers.ListSubscriptionsPager
+ name: subscriber.pagers
+ uid: google.pubsub_v1.services.subscriber.pagers
+ name: Services
+ name: google-cloud-pubsub
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/upgrading.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/upgrading.md
new file mode 100644
index 000000000000..7d5ca89a6f0e
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/gapic-combo/upgrading.md
@@ -0,0 +1,201 @@
+# 2.0.0 Migration Guide
+
+The 2.0 release of the `google-cloud-pubsub` client is a significant upgrade based
+on a [next-gen code generator](https://github.com/googleapis/gapic-generator-python),
+and includes substantial interface changes. Existing code written for earlier versions
+of this library will likely require updates to use this version. This document
+describes the changes that have been made, and what you need to do to update your usage.
+
+If you experience issues or have questions, please file an
+[issue](https://github.com/googleapis/python-pubsub/issues).
+
+## Supported Python Versions
+
+> **WARNING**: Breaking change
+
+The 2.0.0 release requires Python 3.6+.
+
+## Method Calls
+
+> **WARNING**: Breaking change
+
+Almost all methods that send requests to the backend expect request objects. We
+provide a script that will convert most common use cases.
+
+
+* Install the library with the `libcst` extra.
+
+```py
+python3 -m pip install google-cloud-pubsub[libcst]
+```
+
+
+* The script `fixup_pubsub_v1_keywords.py` is shipped with the library. It expects
+an input directory (with the code to convert) and an empty destination directory.
+
+```sh
+$ scripts/fixup_pubsub_v1_keywords.py --input-directory .samples/ --output-directory samples/
+```
+
+**Before:**
+
+```py
+from google.cloud import pubsub
+
+publisher = pubsub.PublisherClient()
+
+project_path = "projects/{}".format(PROJECT_ID)
+topics = publisher.list_topics(project_path)
+```
+
+**After:**
+
+```py
+from google.cloud import pubsub
+
+publisher = pubsub.PublisherClient()
+
+project_path = f"projects/{PROJECT_ID}"
+topics = publisher.list_topics(request={"project": project_path})
+```
+
+### More Details
+
+In `google-cloud-pubsub<2.0.0`, parameters required by the API were positional
+parameters and optional parameters were keyword parameters.
+
+**Before:**
+
+```py
+ def list_topics(
+ self,
+ project,
+ page_size=None,
+ retry=google.api_core.gapic_v1.method.DEFAULT,
+ timeout=google.api_core.gapic_v1.method.DEFAULT,
+ metadata=None,
+ ):
+```
+
+In the 2.0.0 release, almost all methods that interact with the backend have a single
+positional parameter `request`. Method docstrings indicate whether a parameter is
+required or optional.
+
+> **NOTE:** The exception are hand written methods such as `publisher.publish()` and
+> `subscriber.subscribe()` that implement additional logic (e.g. request batching) and
+> sit on top of the API methods from the generated parts of the library. The signatures
+> of these methods have in large part been preserved.
+
+Some methods have additional keyword only parameters. The available parameters depend
+on the [`google.api.method_signature` annotation](https://github.com/googleapis/python-pubsub/blob/main/google/cloud/pubsub_v1/proto/pubsub.proto#L88)
+specified by the API producer.
+
+**After:**
+
+```py
+ def list_topics(
+ self,
+ request: pubsub.ListTopicsRequest = None,
+ *,
+ project: str = None,
+ retry: retries.Retry = gapic_v1.method.DEFAULT,
+ timeout: google.pubsub_v1.types.TimeoutType = gapic_v1.method.DEFAULT,
+ metadata: Sequence[Tuple[str, str]] = (),
+ ) -> pagers.ListTopicsPager:
+```
+
+> **NOTE:** The `request` parameter and flattened keyword parameters for the API are
+> mutually exclusive. Passing both will result in an error.
+
+Both of these calls are valid:
+
+```py
+response = client.list_topics(
+ request={
+ "project": project_path,
+ "metadata": [("foo", "bar"), ("baz", "quux")],
+ }
+)
+```
+
+```py
+response = client.list_topics(
+ project=project_path,
+ metadata=[("foo", "bar"), ("baz", "quux")],
+)
+```
+
+This call is invalid because it mixes `request` with a keyword argument `metadata`.
+Executing this code will result in an error:
+
+```py
+response = client.synthesize_speech(
+ request={"project": project_path},
+ metadata=[("foo", "bar"), ("baz", "quux")],
+)
+```
+
+> **NOTE:** The `request` parameter of some methods can also contain a more rich set of
+> options that are otherwise not available as explicit keyword only parameters, thus
+> these *must* be passed through `request`.
+
+## Removed Utility Methods
+
+> **WARNING**: Breaking change
+
+Some utility methods such as publisher client’s `subscription_path()` have been removed
+and now only exist in the relevant client, e.g. `subscriber.subscription_path()`.
+
+The `project_path()` method has been removed from both the publisher and subscriber
+client, this path must now be constructed manually:
+
+```py
+project_path = f"projects/{PROJECT_ID}"
+```
+
+## Removed `client_config` Parameter
+
+The publisher and subscriber clients cannot be constructed with `client_config`
+argument anymore. If you want to customize retry and timeout settings for a particular
+method, you need to do it upon method invocation by passing the custom `timeout` and
+`retry` arguments, respectively.
+
+## Custom Retry and Timeout settings for Publisher Client
+
+The `publisher_options` parameter to the Publisher Client, as well as all of the
+client’s methods, now accept custom retry and timeout settings:
+
+```py
+custom_retry = api_core.retry.Retry(
+ initial=0.250, # seconds (default: 0.1)
+ maximum=90.0, # seconds (default: 60.0)
+ multiplier=1.45, # default: 1.3
+ deadline=300.0, # seconds (default: 60.0)
+ predicate=api_core.retry.if_exception_type(
+ api_core.exceptions.Aborted,
+ api_core.exceptions.DeadlineExceeded,
+ api_core.exceptions.InternalServerError,
+ api_core.exceptions.ResourceExhausted,
+ api_core.exceptions.ServiceUnavailable,
+ api_core.exceptions.Unknown,
+ api_core.exceptions.Cancelled,
+ ),
+)
+
+custom_timeout=api_core.timeout.ExponentialTimeout(
+ initial=1.0,
+ maximum=10.0,
+ multiplier=1.0,
+ deadline=300.0,
+)
+
+publisher = pubsub_v1.PublisherClient(
+ publisher_options = pubsub_v1.types.PublisherOptions(
+ retry=custom_retry,
+ timeout=custom_timeout,
+ ),
+)
+```
+
+The timeout can be either an instance of `google.api_core.timeout.ConstantTimeout`,
+or an instance of `google.api_core.timeout.ExponentialTimeout`, as in the example.
diff --git a/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/handwritten/blobs.md b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/handwritten/blobs.md
new file mode 100644
index 000000000000..235672cbffd1
--- /dev/null
+++ b/packages/gcp-sphinx-docfx-yaml/tests/testdata/goldens/handwritten/blobs.md
@@ -0,0 +1,2518 @@
+# Blobs / Objects
+
+Create / interact with Google Cloud Storage blobs.
+
+
+### _class_ google.cloud.storage.blob.Blob(name, bucket, chunk_size=None, encryption_key=None, kms_key_name=None, generation=None)
+Bases: `google.cloud.storage._helpers._PropertyMixin`
+
+A wrapper around Cloud Storage’s concept of an `Object`.
+
+
+* **Parameters**
+
+
+ * **name** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – The name of the blob. This corresponds to the unique path of
+ the object in the bucket. If bytes, will be converted to a
+ unicode object. Blob / object names can contain any sequence
+ of valid unicode characters, of length 1-1024 bytes when
+ UTF-8 encoded.
+
+
+ * **bucket** ([`google.cloud.storage.bucket.Bucket`](buckets.md#google.cloud.storage.bucket.Bucket)) – The bucket to which this blob belongs.
+
+
+ * **chunk_size** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The size of a chunk of data whenever iterating (in bytes).
+ This must be a multiple of 256 KB per the API specification. If not
+ specified, the chunk_size of the blob itself is used. If that is not
+ specified, a default value of 40 MB is used.
+
+
+ * **encryption_key** ([*bytes*](https://python.readthedocs.io/en/latest/library/stdtypes.html#bytes)) – (Optional) 32 byte encryption key for customer-supplied encryption.
+ See [https://cloud.google.com/storage/docs/encryption#customer-supplied](https://cloud.google.com/storage/docs/encryption#customer-supplied).
+
+
+ * **kms_key_name** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) Resource name of Cloud KMS key used to encrypt the blob’s
+ contents.
+
+
+ * **generation** (*long*) – (Optional) If present, selects a specific revision of this object.
+
+
+property `name`
+
+ Get the blob’s name.
+
+
+#### STORAGE_CLASSES(_ = ('STANDARD', 'NEARLINE', 'COLDLINE', 'ARCHIVE', 'MULTI_REGIONAL', 'REGIONAL'_ )
+Allowed values for `storage_class`.
+
+See
+[https://cloud.google.com/storage/docs/json_api/v1/objects#storageClass](https://cloud.google.com/storage/docs/json_api/v1/objects#storageClass)
+[https://cloud.google.com/storage/docs/per-object-storage-class](https://cloud.google.com/storage/docs/per-object-storage-class)
+
+**NOTE**: This list does not include ‘DURABLE_REDUCED_AVAILABILITY’, which
+is only documented for buckets (and deprecated).
+
+
+#### _property_ acl()
+Create our ACL on demand.
+
+
+#### _property_ bucket()
+Bucket which contains the object.
+
+
+* **Return type**
+
+ [`Bucket`](buckets.md#google.cloud.storage.bucket.Bucket)
+
+
+
+* **Returns**
+
+ The object’s bucket.
+
+
+
+#### _property_ cache_control()
+HTTP ‘Cache-Control’ header for this object.
+
+See [RFC 7234]([https://tools.ietf.org/html/rfc7234#section-5.2](https://tools.ietf.org/html/rfc7234#section-5.2))
+and [API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+#### _property_ chunk_size()
+Get the blob’s default chunk size.
+
+
+* **Return type**
+
+ int or `NoneType`
+
+
+
+* **Returns**
+
+ The current blob’s chunk size, if it is set.
+
+
+
+#### _property_ client()
+The client bound to this blob.
+
+
+#### _property_ component_count()
+Number of underlying components that make up this object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ int or `NoneType`
+
+
+
+* **Returns**
+
+ The component count (in case of a composed object) or
+ `None` if the blob’s resource has not been loaded from
+ the server. This property will not be set on objects
+ not created via `compose`.
+
+
+
+#### compose(sources, client=None, timeout=60, if_generation_match=None, if_metageneration_match=None, if_source_generation_match=None, retry=)
+Concatenate source blobs into this one.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+See [API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects/compose](https://cloud.google.com/storage/docs/json_api/v1/objects/compose))
+and a [code sample]([https://cloud.google.com/storage/docs/samples/storage-compose-file#storage_compose_file-python](https://cloud.google.com/storage/docs/samples/storage-compose-file#storage_compose_file-python)).
+
+
+* **Parameters**
+
+
+ * **sources** (list of `Blob`) – Blobs whose contents will be composed into this blob.
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **if_generation_match** (*long*) – (Optional) Makes the operation conditional on whether the
+ destination object’s current generation matches the given value.
+ Setting to 0 makes the operation succeed only if there are no live
+ versions of the object.
+ Note: In a previous version, this argument worked identically to the
+ `if_source_generation_match` argument. For
+ backwards-compatibility reasons, if a list is passed in,
+ this argument will behave like `if_source_generation_match`
+ and also issue a DeprecationWarning.
+
+
+ * **if_metageneration_match** (*long*) – (Optional) Makes the operation conditional on whether the
+ destination object’s current metageneration matches the given
+ value.
+
+ If a list of long is passed in, no match operation will be
+ performed. (Deprecated: type(list of long) is supported for
+ backwards-compatability reasons only.)
+
+
+
+ * **if_source_generation_match** (*list of long*) – (Optional) Makes the operation conditional on whether the current
+ generation of each source blob matches the corresponding generation.
+ The list must match `sources` item-to-item.
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+#### _property_ content_disposition()
+HTTP ‘Content-Disposition’ header for this object.
+
+See [RFC 6266]([https://tools.ietf.org/html/rfc7234#section-5.2](https://tools.ietf.org/html/rfc7234#section-5.2)) and
+[API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+#### _property_ content_encoding()
+HTTP ‘Content-Encoding’ header for this object.
+
+See [RFC 7231]([https://tools.ietf.org/html/rfc7231#section-3.1.2.2](https://tools.ietf.org/html/rfc7231#section-3.1.2.2)) and
+[API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+#### _property_ content_language()
+HTTP ‘Content-Language’ header for this object.
+
+See [BCP47]([https://tools.ietf.org/html/bcp47](https://tools.ietf.org/html/bcp47)) and
+[API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+#### _property_ content_type()
+HTTP ‘Content-Type’ header for this object.
+
+See [RFC 2616]([https://tools.ietf.org/html/rfc2616#section-14.17](https://tools.ietf.org/html/rfc2616#section-14.17)) and
+[API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+#### _property_ crc32c()
+CRC32C checksum for this object.
+
+This returns the blob’s CRC32C checksum. To retrieve the value, first use a
+reload method of the Blob class which loads the blob’s properties from the server.
+
+See [RFC 4960]([https://tools.ietf.org/html/rfc4960#appendix-B](https://tools.ietf.org/html/rfc4960#appendix-B)) and
+[API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+If not set before upload, the server will compute the hash.
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+#### create_resumable_upload_session(content_type=None, size=None, origin=None, client=None, timeout=60, checksum=None, predefined_acl=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=)
+Create a resumable upload session.
+
+Resumable upload sessions allow you to start an upload session from
+one client and complete the session in another. This method is called
+by the initiator to set the metadata and limits. The initiator then
+passes the session URL to the client that will upload the binary data.
+The client performs a PUT request on the session URL to complete the
+upload. This process allows untrusted clients to upload to an
+access-controlled bucket.
+
+For more details, see the
+documentation on [signed URLs]([https://cloud.google.com/storage/docs/access-control/signed-urls#signing-resumable](https://cloud.google.com/storage/docs/access-control/signed-urls#signing-resumable)).
+
+The content type of the upload will be determined in order
+of precedence:
+
+
+* The value passed in to this method (if not [`None`](https://python.readthedocs.io/en/latest/library/constants.html#None))
+
+
+* The value stored on the current blob
+
+
+* The default value (‘application/octet-stream’)
+
+**NOTE**: The effect of uploading to an existing blob depends on the
+“versioning” and “lifecycle” policies defined on the blob’s
+bucket. In the absence of those policies, upload will
+overwrite any existing contents.
+
+See the [object versioning]([https://cloud.google.com/storage/docs/object-versioning](https://cloud.google.com/storage/docs/object-versioning))
+and [lifecycle]([https://cloud.google.com/storage/docs/lifecycle](https://cloud.google.com/storage/docs/lifecycle))
+API documents for details.
+
+If `encryption_key` is set, the blob will be encrypted with
+a [customer-supplied]([https://cloud.google.com/storage/docs/encryption#customer-supplied](https://cloud.google.com/storage/docs/encryption#customer-supplied))
+encryption key.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **size** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The maximum number of bytes that can be uploaded using
+ this session. If the size is not known when creating the session,
+ this should be left blank.
+
+
+ * **content_type** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) Type of content being uploaded.
+
+
+ * **origin** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) If set, the upload can only be completed by a user-agent
+ that uploads from the given origin. This can be useful when passing
+ the session to a web client.
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **checksum** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) The type of checksum to compute to verify
+ the integrity of the object. After the upload is complete, the
+ server-computed checksum of the resulting object will be checked
+ and google.resumable_media.common.DataCorruption will be raised on
+ a mismatch. On a validation failure, the client will attempt to
+ delete the uploaded object automatically. Supported values
+ are “md5”, “crc32c” and None. The default is None.
+
+
+ * **predefined_acl** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) Predefined access control list
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disable
+ retries. A google.api_core.retry.Retry value will enable retries,
+ and the object will define retriable response codes and errors and
+ configure backoff and timeout options.
+ A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
+ Retry object and activates it only if certain conditions are met.
+ This class exists to provide safe defaults for RPC calls that are
+ not technically safe to retry normally (due to potential data
+ duplication or other side-effects) but become safe to retry if a
+ condition such as if_generation_match is set.
+ See the retry.py source code and docstrings in this package
+ (google.cloud.storage.retry) for information on retry types and how
+ to configure them.
+ Media operations (downloads and uploads) do not support non-default
+ predicates in a Retry object. The default will always be used. Other
+ configuration changes for Retry objects such as delays and deadlines
+ are respected.
+
+
+
+* **Return type**
+
+ [str](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)
+
+
+
+* **Returns**
+
+ The resumable upload session URL. The upload can be
+ completed by making an HTTP PUT request with the
+ file’s contents.
+
+
+
+* **Raises**
+
+ `google.cloud.exceptions.GoogleCloudError`
+ if the session creation response returns an error status.
+
+
+
+#### _property_ custom_time()
+Retrieve the custom time for the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ [`datetime.datetime`](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.datetime) or `NoneType`
+
+
+
+* **Returns**
+
+ Datetime object parsed from RFC3339 valid timestamp, or
+ `None` if the blob’s resource has not been loaded from
+ the server (see `reload()`).
+
+
+
+#### delete(client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=)
+Deletes a blob from Cloud Storage.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+* **Raises**
+
+ `google.cloud.exceptions.NotFound`
+ (propagated from
+ [`google.cloud.storage.bucket.Bucket.delete_blob()`](buckets.md#google.cloud.storage.bucket.Bucket.delete_blob)).
+
+
+
+#### download_as_bytes(client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='md5', retry=)
+Download the contents of this blob as a bytes object.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **start** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The first byte in a range to be downloaded.
+
+
+ * **end** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The last byte in a range to be downloaded.
+
+
+ * **raw_download** ([*bool*](https://python.readthedocs.io/en/latest/library/functions.html#bool)) – (Optional) If true, download the object without any expansion.
+
+
+ * **if_etag_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_match](generation_metageneration.md#using-if-etag-match)
+
+
+ * **if_etag_not_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_not_match](generation_metageneration.md#using-if-etag-not-match)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **checksum** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) The type of checksum to compute to verify the integrity
+ of the object. The response headers must contain a checksum of the
+ requested type. If the headers lack an appropriate checksum (for
+ instance in the case of transcoded or ranged downloads where the
+ remote service does not know the correct checksum, including
+ downloads where chunk_size is set) an INFO-level log will be
+ emitted. Supported values are “md5”, “crc32c” and None. The default
+ is “md5”.
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disable
+ retries. A google.api_core.retry.Retry value will enable retries,
+ and the object will define retriable response codes and errors and
+ configure backoff and timeout options.
+
+ A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
+ Retry object and activates it only if certain conditions are met.
+ This class exists to provide safe defaults for RPC calls that are
+ not technically safe to retry normally (due to potential data
+ duplication or other side-effects) but become safe to retry if a
+ condition such as if_metageneration_match is set.
+
+ See the retry.py source code and docstrings in this package
+ (google.cloud.storage.retry) for information on retry types and how
+ to configure them.
+
+ Media operations (downloads and uploads) do not support non-default
+ predicates in a Retry object. The default will always be used. Other
+ configuration changes for Retry objects such as delays and deadlines
+ are respected.
+
+
+
+
+* **Return type**
+
+ [bytes](https://python.readthedocs.io/en/latest/library/stdtypes.html#bytes)
+
+
+
+* **Returns**
+
+ The data stored in this blob.
+
+
+
+* **Raises**
+
+ `google.cloud.exceptions.NotFound`
+
+
+
+#### download_as_string(client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=)
+(Deprecated) Download the contents of this blob as a bytes object.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+**NOTE**: Deprecated alias for `download_as_bytes()`.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **start** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The first byte in a range to be downloaded.
+
+
+ * **end** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The last byte in a range to be downloaded.
+
+
+ * **raw_download** ([*bool*](https://python.readthedocs.io/en/latest/library/functions.html#bool)) – (Optional) If true, download the object without any expansion.
+
+
+ * **if_etag_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_match](generation_metageneration.md#using-if-etag-match)
+
+
+ * **if_etag_not_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_not_match](generation_metageneration.md#using-if-etag-not-match)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disable
+ retries. A google.api_core.retry.Retry value will enable retries,
+ and the object will define retriable response codes and errors and
+ configure backoff and timeout options.
+
+ A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
+ Retry object and activates it only if certain conditions are met.
+ This class exists to provide safe defaults for RPC calls that are
+ not technically safe to retry normally (due to potential data
+ duplication or other side-effects) but become safe to retry if a
+ condition such as if_metageneration_match is set.
+
+ See the retry.py source code and docstrings in this package
+ (google.cloud.storage.retry) for information on retry types and how
+ to configure them.
+
+ Media operations (downloads and uploads) do not support non-default
+ predicates in a Retry object. The default will always be used. Other
+ configuration changes for Retry objects such as delays and deadlines
+ are respected.
+
+
+
+
+* **Return type**
+
+ [bytes](https://python.readthedocs.io/en/latest/library/stdtypes.html#bytes)
+
+
+
+* **Returns**
+
+ The data stored in this blob.
+
+
+
+* **Raises**
+
+ `google.cloud.exceptions.NotFound`
+
+
+
+#### download_as_text(client=None, start=None, end=None, raw_download=False, encoding=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=)
+Download the contents of this blob as text (*not* bytes).
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **start** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The first byte in a range to be downloaded.
+
+
+ * **end** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The last byte in a range to be downloaded.
+
+
+ * **raw_download** ([*bool*](https://python.readthedocs.io/en/latest/library/functions.html#bool)) – (Optional) If true, download the object without any expansion.
+
+
+ * **encoding** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) encoding to be used to decode the
+ downloaded bytes. Defaults to the `charset` param of
+ attr:content_type, or else to “utf-8”.
+
+
+ * **if_etag_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_match](generation_metageneration.md#using-if-etag-match)
+
+
+ * **if_etag_not_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_not_match](generation_metageneration.md#using-if-etag-not-match)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disable
+ retries. A google.api_core.retry.Retry value will enable retries,
+ and the object will define retriable response codes and errors and
+ configure backoff and timeout options.
+
+ A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
+ Retry object and activates it only if certain conditions are met.
+ This class exists to provide safe defaults for RPC calls that are
+ not technically safe to retry normally (due to potential data
+ duplication or other side-effects) but become safe to retry if a
+ condition such as if_metageneration_match is set.
+
+ See the retry.py source code and docstrings in this package
+ (google.cloud.storage.retry) for information on retry types and how
+ to configure them.
+
+ Media operations (downloads and uploads) do not support non-default
+ predicates in a Retry object. The default will always be used. Other
+ configuration changes for Retry objects such as delays and deadlines
+ are respected.
+
+
+
+
+* **Return type**
+
+ text
+
+
+
+* **Returns**
+
+ The data stored in this blob, decoded to text.
+
+
+
+#### download_to_file(file_obj, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='md5', retry=)
+DEPRECATED. Download the contents of this blob into a file-like object.
+
+**NOTE**: If the server-set property, `media_link`, is not yet
+initialized, makes an additional API request to load it.
+
+If the `chunk_size` of a current blob is None, will download data
+in single download request otherwise it will download the `chunk_size`
+of data in each request.
+
+For more fine-grained control over the download process, check out
+[google-resumable-media]([https://googleapis.dev/python/google-resumable-media/latest/index.html](https://googleapis.dev/python/google-resumable-media/latest/index.html)).
+For example, this library allows downloading **parts** of a blob rather than the whole thing.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **file_obj** (*file*) – A file handle to which to write the blob’s data.
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **start** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The first byte in a range to be downloaded.
+
+
+ * **end** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The last byte in a range to be downloaded.
+
+
+ * **raw_download** ([*bool*](https://python.readthedocs.io/en/latest/library/functions.html#bool)) – (Optional) If true, download the object without any expansion.
+
+
+ * **if_etag_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_match](generation_metageneration.md#using-if-etag-match)
+
+
+ * **if_etag_not_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_not_match](generation_metageneration.md#using-if-etag-not-match)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **checksum** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) The type of checksum to compute to verify the integrity
+ of the object. The response headers must contain a checksum of the
+ requested type. If the headers lack an appropriate checksum (for
+ instance in the case of transcoded or ranged downloads where the
+ remote service does not know the correct checksum, including
+ downloads where chunk_size is set) an INFO-level log will be
+ emitted. Supported values are “md5”, “crc32c” and None. The default
+ is “md5”.
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disable
+ retries. A google.api_core.retry.Retry value will enable retries,
+ and the object will define retriable response codes and errors and
+ configure backoff and timeout options.
+
+ A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
+ Retry object and activates it only if certain conditions are met.
+ This class exists to provide safe defaults for RPC calls that are
+ not technically safe to retry normally (due to potential data
+ duplication or other side-effects) but become safe to retry if a
+ condition such as if_metageneration_match is set.
+
+ See the retry.py source code and docstrings in this package
+ (google.cloud.storage.retry) for information on retry types and how
+ to configure them.
+
+ Media operations (downloads and uploads) do not support non-default
+ predicates in a Retry object. The default will always be used. Other
+ configuration changes for Retry objects such as delays and deadlines
+ are respected.
+
+
+
+
+* **Raises**
+
+ `google.cloud.exceptions.NotFound`
+
+
+
+#### download_to_filename(filename, client=None, start=None, end=None, raw_download=False, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, checksum='md5', retry=)
+Download the contents of this blob into a named file.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+See a [code sample]([https://cloud.google.com/storage/docs/samples/storage-download-encrypted-file#storage_download_encrypted_file-python](https://cloud.google.com/storage/docs/samples/storage-download-encrypted-file#storage_download_encrypted_file-python))
+to download a file with a [customer-supplied encryption key]([https://cloud.google.com/storage/docs/encryption#customer-supplied](https://cloud.google.com/storage/docs/encryption#customer-supplied)).
+
+
+* **Parameters**
+
+
+ * **filename** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – A filename to be passed to `open`.
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **start** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The first byte in a range to be downloaded.
+
+
+ * **end** ([*int*](https://python.readthedocs.io/en/latest/library/functions.html#int)) – (Optional) The last byte in a range to be downloaded.
+
+
+ * **raw_download** ([*bool*](https://python.readthedocs.io/en/latest/library/functions.html#bool)) – (Optional) If true, download the object without any expansion.
+
+
+ * **if_etag_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_match](generation_metageneration.md#using-if-etag-match)
+
+
+ * **if_etag_not_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_not_match](generation_metageneration.md#using-if-etag-not-match)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **checksum** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) The type of checksum to compute to verify the integrity
+ of the object. The response headers must contain a checksum of the
+ requested type. If the headers lack an appropriate checksum (for
+ instance in the case of transcoded or ranged downloads where the
+ remote service does not know the correct checksum, including
+ downloads where chunk_size is set) an INFO-level log will be
+ emitted. Supported values are “md5”, “crc32c” and None. The default
+ is “md5”.
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. A None value will disable
+ retries. A google.api_core.retry.Retry value will enable retries,
+ and the object will define retriable response codes and errors and
+ configure backoff and timeout options.
+
+ A google.cloud.storage.retry.ConditionalRetryPolicy value wraps a
+ Retry object and activates it only if certain conditions are met.
+ This class exists to provide safe defaults for RPC calls that are
+ not technically safe to retry normally (due to potential data
+ duplication or other side-effects) but become safe to retry if a
+ condition such as if_metageneration_match is set.
+
+ See the retry.py source code and docstrings in this package
+ (google.cloud.storage.retry) for information on retry types and how
+ to configure them.
+
+ Media operations (downloads and uploads) do not support non-default
+ predicates in a Retry object. The default will always be used. Other
+ configuration changes for Retry objects such as delays and deadlines
+ are respected.
+
+
+
+
+* **Raises**
+
+ `google.cloud.exceptions.NotFound`
+
+
+
+#### _property_ encryption_key()
+Retrieve the customer-supplied encryption key for the object.
+
+
+* **Return type**
+
+ bytes or `NoneType`
+
+
+
+* **Returns**
+
+ The encryption key or `None` if no customer-supplied encryption key was used,
+ or the blob’s resource has not been loaded from the server.
+
+
+
+#### _property_ etag()
+Retrieve the ETag for the object.
+
+See [RFC 2616 (etags)]([https://tools.ietf.org/html/rfc2616#section-3.11](https://tools.ietf.org/html/rfc2616#section-3.11)) and
+[API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+* **Returns**
+
+ The blob etag or `None` if the blob’s resource has not
+ been loaded from the server.
+
+
+
+#### _property_ event_based_hold()
+Is an event-based hold active on the object?
+
+See [API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+If the property is not set locally, returns [`None`](https://python.readthedocs.io/en/latest/library/constants.html#None).
+
+
+* **Return type**
+
+ bool or `NoneType`
+
+
+
+#### exists(client=None, if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=)
+Determines whether or not this blob exists.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **if_etag_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_match](generation_metageneration.md#using-if-etag-match)
+
+
+ * **if_etag_not_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_not_match](generation_metageneration.md#using-if-etag-not-match)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+* **Return type**
+
+ [bool](https://python.readthedocs.io/en/latest/library/functions.html#bool)
+
+
+
+* **Returns**
+
+ True if the blob exists in Cloud Storage.
+
+
+
+#### _classmethod_ from_string(uri, client=None)
+Get a constructor for blob object by URI.
+
+```python
+from google.cloud import storage
+from google.cloud.storage.blob import Blob
+client = storage.Client()
+blob = Blob.from_string("gs://bucket/object", client=client)
+```
+
+
+* **Parameters**
+
+
+ * **uri** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – The blob uri pass to get blob object.
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. Application code should
+ *always* pass `client`.
+
+
+
+* **Return type**
+
+ `google.cloud.storage.blob.Blob`
+
+
+
+* **Returns**
+
+ The blob object created.
+
+
+
+#### generate_signed_url(expiration=None, api_access_endpoint='https://storage.googleapis.com', method='GET', content_md5=None, content_type=None, response_disposition=None, response_type=None, generation=None, headers=None, query_parameters=None, client=None, credentials=None, version=None, service_account_email=None, access_token=None, virtual_hosted_style=False, bucket_bound_hostname=None, scheme='http')
+Generates a signed URL for this blob.
+
+**NOTE**: If you are on Google Compute Engine, you can’t generate a signed
+URL using GCE service account.
+If you’d like to be able to generate a signed URL from GCE,
+you can use a standard service account from a JSON file rather
+than a GCE service account.
+
+If you have a blob that you want to allow access to for a set
+amount of time, you can use this method to generate a URL that
+is only valid within a certain time period.
+
+See a [code sample]([https://cloud.google.com/storage/docs/samples/storage-generate-signed-url-v4#storage_generate_signed_url_v4-python](https://cloud.google.com/storage/docs/samples/storage-generate-signed-url-v4#storage_generate_signed_url_v4-python)).
+
+This is particularly useful if you don’t want publicly
+accessible blobs, but don’t want to require users to explicitly
+log in.
+
+If `bucket_bound_hostname` is set as an argument of `api_access_endpoint`,
+`https` works only if using a `CDN`.
+
+
+* **Parameters**
+
+
+ * **expiration** (*Union**[**Integer**, *[*datetime.datetime*](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.datetime)*, *[*datetime.timedelta*](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.timedelta)*]*) – Point in time when the signed URL should expire. If a `datetime`
+ instance is passed without an explicit `tzinfo` set, it will be
+ assumed to be `UTC`.
+
+
+ * **api_access_endpoint** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) URI base.
+
+
+ * **method** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – The HTTP verb that will be used when requesting the URL.
+
+
+ * **content_md5** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) The MD5 hash of the object referenced by `resource`.
+
+
+ * **content_type** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) The content type of the object referenced by
+ `resource`.
+
+
+ * **response_disposition** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) Content disposition of responses to requests for the
+ signed URL. For example, to enable the signed URL to initiate a
+ file of `blog.png`, use the value `'attachment;
+ filename=blob.png'`.
+
+
+ * **response_type** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) Content type of responses to requests for the signed
+ URL. Ignored if content_type is set on object/blob metadata.
+
+
+ * **generation** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) A value that indicates which generation of the resource
+ to fetch.
+
+
+ * **headers** ([*dict*](https://python.readthedocs.io/en/latest/library/stdtypes.html#dict)) – (Optional) Additional HTTP headers to be included as part of the
+ signed URLs. See:
+ [https://cloud.google.com/storage/docs/xml-api/reference-headers](https://cloud.google.com/storage/docs/xml-api/reference-headers)
+ Requests using the signed URL *must* pass the specified header
+ (name and value) with each request for the URL.
+
+
+ * **query_parameters** ([*dict*](https://python.readthedocs.io/en/latest/library/stdtypes.html#dict)) – (Optional) Additional query parameters to be included as part of the
+ signed URLs. See:
+ [https://cloud.google.com/storage/docs/xml-api/reference-headers#query](https://cloud.google.com/storage/docs/xml-api/reference-headers#query)
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **credentials** ([`google.auth.credentials.Credentials`](https://googleapis.dev/python/google-auth/latest/reference/google.auth.credentials.html#google.auth.credentials.Credentials)) – (Optional) The authorization credentials to attach to requests.
+ These credentials identify this application to the service. If
+ none are specified, the client will attempt to ascertain the
+ credentials from the environment.
+
+
+ * **version** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) The version of signed credential to create. Must be one
+ of ‘v2’ | ‘v4’.
+
+
+ * **service_account_email** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) E-mail address of the service account.
+
+
+ * **access_token** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) Access token for a service account.
+
+
+ * **virtual_hosted_style** ([*bool*](https://python.readthedocs.io/en/latest/library/functions.html#bool)) – (Optional) If true, then construct the URL relative the bucket’s
+ virtual hostname, e.g., ‘.storage.googleapis.com’.
+
+
+ * **bucket_bound_hostname** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) If passed, then construct the URL relative to the
+ bucket-bound hostname. Value can be a bare or with scheme, e.g.,
+ ‘example.com’ or ‘[http://example.com](http://example.com)’. See:
+ [https://cloud.google.com/storage/docs/request-endpoints#cname](https://cloud.google.com/storage/docs/request-endpoints#cname)
+
+
+ * **scheme** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) If `bucket_bound_hostname` is passed as a bare
+ hostname, use this value as the scheme. `https` will work only
+ when using a CDN. Defaults to `"http"`.
+
+
+
+* **Raises**
+
+ [`ValueError`](https://python.readthedocs.io/en/latest/library/exceptions.html#ValueError) when version is invalid.
+
+
+
+* **Raises**
+
+ [`TypeError`](https://python.readthedocs.io/en/latest/library/exceptions.html#TypeError) when expiration is not a valid type.
+
+
+
+* **Raises**
+
+ [`AttributeError`](https://python.readthedocs.io/en/latest/library/exceptions.html#AttributeError) if credentials is not an instance
+ of [`google.auth.credentials.Signing`](https://googleapis.dev/python/google-auth/latest/reference/google.auth.credentials.html#google.auth.credentials.Signing).
+
+
+
+* **Return type**
+
+ [str](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)
+
+
+
+* **Returns**
+
+ A signed URL you can use to access the resource
+ until expiration.
+
+
+
+#### _property_ generation()
+Retrieve the generation for the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ int or `NoneType`
+
+
+
+* **Returns**
+
+ The generation of the blob or `None` if the blob’s
+ resource has not been loaded from the server.
+
+
+
+#### get_iam_policy(client=None, requested_policy_version=None, timeout=60, retry=)
+Retrieve the IAM policy for the object.
+
+**NOTE**: Blob- / object-level IAM support does not yet exist and methods
+currently call an internal ACL backend not providing any utility
+beyond the blob’s `acl` at this time. The API may be enhanced
+in the future and is currently undocumented. Use `acl` for
+managing object access control.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the current object’s bucket.
+
+
+ * **requested_policy_version** (int or `NoneType`) – (Optional) The version of IAM policies to request. If a policy
+ with a condition is requested without setting this, the server will
+ return an error. This must be set to a value of 3 to retrieve IAM
+ policies containing conditions. This is to prevent client code that
+ isn’t aware of IAM conditions from interpreting and modifying
+ policies incorrectly. The service might return a policy with
+ version lower than the one that was requested, based on the feature
+ syntax in the policy fetched.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+* **Return type**
+
+ [`google.api_core.iam.Policy`](https://googleapis.dev/python/google-api-core/latest/iam.html#google.api_core.iam.Policy)
+
+
+
+* **Returns**
+
+ the policy instance, based on the resource returned from
+ the `getIamPolicy` API request.
+
+
+
+#### _property_ id()
+Retrieve the ID for the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+The ID consists of the bucket name, object name, and generation number.
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+* **Returns**
+
+ The ID of the blob or `None` if the blob’s
+ resource has not been loaded from the server.
+
+
+
+#### _property_ kms_key_name()
+Resource name of Cloud KMS key used to encrypt the blob’s contents.
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+* **Returns**
+
+ The resource name or `None` if no Cloud KMS key was used,
+ or the blob’s resource has not been loaded from the server.
+
+
+
+#### make_private(client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=)
+Update blob’s ACL, revoking read access for anonymous users.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client) or
+ `NoneType`) – (Optional) The client to use. If not passed, falls back
+ to the `client` stored on the blob’s bucket.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+#### make_public(client=None, timeout=60, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, retry=)
+Update blob’s ACL, granting read access to anonymous users.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client) or
+ `NoneType`) – (Optional) The client to use. If not passed, falls back
+ to the `client` stored on the blob’s bucket.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+#### _property_ md5_hash()
+MD5 hash for this object.
+
+This returns the blob’s MD5 hash. To retrieve the value, first use a
+reload method of the Blob class which loads the blob’s properties from the server.
+
+See [RFC 1321]([https://tools.ietf.org/html/rfc1321](https://tools.ietf.org/html/rfc1321)) and
+[API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+If not set before upload, the server will compute the hash.
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+#### _property_ media_link()
+Retrieve the media download URI for the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+* **Returns**
+
+ The media link for the blob or `None` if the blob’s
+ resource has not been loaded from the server.
+
+
+
+#### _property_ metadata()
+Retrieve arbitrary/application specific metadata for the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Setter**
+
+ Update arbitrary/application specific metadata for the
+ object.
+
+
+
+* **Getter**
+
+ Retrieve arbitrary/application specific metadata for
+ the object.
+
+
+
+* **Return type**
+
+ dict or `NoneType`
+
+
+
+* **Returns**
+
+ The metadata associated with the blob or `None` if the
+ property is not set.
+
+
+
+#### _property_ metageneration()
+Retrieve the metageneration for the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ int or `NoneType`
+
+
+
+* **Returns**
+
+ The metageneration of the blob or `None` if the blob’s
+ resource has not been loaded from the server.
+
+
+
+#### open(mode='r', chunk_size=None, ignore_flush=None, encoding=None, errors=None, newline=None, \*\*kwargs)
+Create a file handler for file-like I/O to or from this blob.
+
+This method can be used as a context manager, just like Python’s
+built-in ‘open()’ function.
+
+While reading, as with other read methods, if blob.generation is not set
+the most recent blob generation will be used. Because the file-like IO
+reader downloads progressively in chunks, this could result in data from
+multiple versions being mixed together. If this is a concern, use
+either bucket.get_blob(), or blob.reload(), which will download the
+latest generation number and set it; or, if the generation is known, set
+it manually, for instance with bucket.blob(generation=123456).
+
+Checksumming (hashing) to verify data integrity is disabled for reads
+using this feature because reads are implemented using request ranges,
+which do not provide checksums to validate. See
+[https://cloud.google.com/storage/docs/hashes-etags](https://cloud.google.com/storage/docs/hashes-etags) for details.
+
+See a [code sample]([https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_fileio_write_read.py](https://github.com/googleapis/python-storage/blob/main/samples/snippets/storage_fileio_write_read.py)).
+
+Keyword arguments to pass to the underlying API calls.
+For both uploads and downloads, the following arguments are
+supported:
+
+
+* `if_generation_match`
+
+
+* `if_generation_not_match`
+
+
+* `if_metageneration_match`
+
+
+* `if_metageneration_not_match`
+
+
+* `timeout`
+
+
+* `retry`
+
+For downloads only, the following additional arguments are supported:
+
+
+* `raw_download`
+
+For uploads only, the following additional arguments are supported:
+
+
+* `content_type`
+
+
+* `num_retries`
+
+
+* `predefined_acl`
+
+
+* `checksum`
+
+**NOTE**: `num_retries` is supported for backwards-compatibility
+reasons only; please use `retry` with a Retry object or
+ConditionalRetryPolicy instead.
+
+
+* **Parameters**
+
+
+ * **mode** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) A mode string, as per standard Python open() semantics.The first
+ character must be ‘r’, to open the blob for reading, or ‘w’ to open
+ it for writing. The second character, if present, must be ‘t’ for
+ (unicode) text mode, or ‘b’ for bytes mode. If the second character
+ is omitted, text mode is the default.
+
+
+ * **chunk_size** (*long*) – (Optional) For reads, the minimum number of bytes to read at a time.
+ If fewer bytes than the chunk_size are requested, the remainder is
+ buffered. For writes, the maximum number of bytes to buffer before
+ sending data to the server, and the size of each request when data
+ is sent. Writes are implemented as a “resumable upload”, so
+ chunk_size for writes must be exactly a multiple of 256KiB as with
+ other resumable uploads. The default is 40 MiB.
+
+
+ * **ignore_flush** ([*bool*](https://python.readthedocs.io/en/latest/library/functions.html#bool)) – (Optional) For non text-mode writes, makes flush() do nothing
+ instead of raising an error. flush() without closing is not
+ supported by the remote service and therefore calling it normally
+ results in io.UnsupportedOperation. However, that behavior is
+ incompatible with some consumers and wrappers of file objects in
+ Python, such as zipfile.ZipFile or io.TextIOWrapper. Setting
+ ignore_flush will cause flush() to successfully do nothing, for
+ compatibility with those contexts. The correct way to actually flush
+ data to the remote server is to close() (using a context manager,
+ such as in the example, will cause this to happen automatically).
+
+
+ * **encoding** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) For text mode only, the name of the encoding that the stream will
+ be decoded or encoded with. If omitted, it defaults to
+ locale.getpreferredencoding(False).
+
+
+ * **errors** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) For text mode only, an optional string that specifies how encoding
+ and decoding errors are to be handled. Pass ‘strict’ to raise a
+ ValueError exception if there is an encoding error (the default of
+ None has the same effect), or pass ‘ignore’ to ignore errors. (Note
+ that ignoring encoding errors can lead to data loss.) Other more
+ rarely-used options are also available; see the Python ‘io’ module
+ documentation for ‘io.TextIOWrapper’ for a complete list.
+
+
+ * **newline** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) For text mode only, controls how line endings are handled. It can
+ be None, ‘’, ‘n’, ‘r’, and ‘rn’. If None, reads use “universal
+ newline mode” and writes use the system default. See the Python
+ ‘io’ module documentation for ‘io.TextIOWrapper’ for details.
+
+
+
+* **Returns**
+
+ A ‘BlobReader’ or ‘BlobWriter’ from
+ ‘google.cloud.storage.fileio’, or an ‘io.TextIOWrapper’ around one
+ of those classes, depending on the ‘mode’ argument.
+
+
+
+#### _property_ owner()
+Retrieve info about the owner of the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ dict or `NoneType`
+
+
+
+* **Returns**
+
+ Mapping of owner’s role/ID, or `None` if the blob’s
+ resource has not been loaded from the server.
+
+
+
+#### patch(client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=)
+Sends all changed properties in a PATCH request.
+
+Updates the `_properties` with the response from the backend.
+
+If `user_project` is set, bills the API request to that project.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client) or
+ `NoneType`) – the client to use. If not passed, falls back to the
+ `client` stored on the current object.
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+#### _property_ path()
+Getter property for the URL path to this Blob.
+
+
+* **Return type**
+
+ [str](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)
+
+
+
+* **Returns**
+
+ The URL path to this Blob.
+
+
+
+#### _static_ path_helper(bucket_path, blob_name)
+Relative URL path for a blob.
+
+
+* **Parameters**
+
+
+ * **bucket_path** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – The URL path for a bucket.
+
+
+ * **blob_name** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – The name of the blob.
+
+
+
+* **Return type**
+
+ [str](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)
+
+
+
+* **Returns**
+
+ The relative URL path for `blob_name`.
+
+
+
+#### _property_ public_url()
+The public URL for this blob.
+
+Use `make_public()` to enable anonymous access via the returned
+URL.
+
+
+* **Return type**
+
+ string
+
+
+
+* **Returns**
+
+ The public URL for this blob.
+
+
+
+#### reload(client=None, projection='noAcl', if_etag_match=None, if_etag_not_match=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=)
+Reload properties from Cloud Storage.
+
+If `user_project` is set, bills the API request to that project.
+
+
+* **Parameters**
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client) or
+ `NoneType`) – the client to use. If not passed, falls back to the
+ `client` stored on the current object.
+
+
+ * **projection** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) If used, must be ‘full’ or ‘noAcl’.
+ Defaults to `'noAcl'`. Specifies the set of
+ properties to return.
+
+
+ * **if_etag_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]*) – (Optional) See [Using if_etag_match](generation_metageneration.md#using-if-etag-match)
+
+
+ * **if_etag_not_match** (*Union**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*, **Set**[*[*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)*]**]**)*) – (Optional) See [Using if_etag_not_match](generation_metageneration.md#using-if-etag-not-match)
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+#### _property_ retention_expiration_time()
+Retrieve timestamp at which the object’s retention period expires.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ [`datetime.datetime`](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.datetime) or `NoneType`
+
+
+
+* **Returns**
+
+ Datetime object parsed from RFC3339 valid timestamp, or
+ `None` if the property is not set locally.
+
+
+
+#### rewrite(source, token=None, client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, if_source_generation_match=None, if_source_generation_not_match=None, if_source_metageneration_match=None, if_source_metageneration_not_match=None, timeout=60, retry=)
+Rewrite source blob into this one.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **source** (`Blob`) – blob whose contents will be rewritten into this blob.
+
+
+ * **token** ([*str*](https://python.readthedocs.io/en/latest/library/stdtypes.html#str)) – (Optional) Token returned from an earlier, not-completed call to
+ rewrite the same source blob. If passed, result will include
+ updated status, total bytes written.
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the blob’s bucket.
+
+
+ * **if_generation_match** (*long*) – (Optional) See [Using if_generation_match](generation_metageneration.md#using-if-generation-match)
+ Note that the generation to be matched is that of the
+ `destination` blob.
+
+
+ * **if_generation_not_match** (*long*) – (Optional) See [Using if_generation_not_match](generation_metageneration.md#using-if-generation-not-match)
+ Note that the generation to be matched is that of the
+ `destination` blob.
+
+
+ * **if_metageneration_match** (*long*) – (Optional) See [Using if_metageneration_match](generation_metageneration.md#using-if-metageneration-match)
+ Note that the metageneration to be matched is that of the
+ `destination` blob.
+
+
+ * **if_metageneration_not_match** (*long*) – (Optional) See [Using if_metageneration_not_match](generation_metageneration.md#using-if-metageneration-not-match)
+ Note that the metageneration to be matched is that of the
+ `destination` blob.
+
+
+ * **if_source_generation_match** (*long*) – (Optional) Makes the operation conditional on whether the source
+ object’s generation matches the given value.
+
+
+ * **if_source_generation_not_match** (*long*) – (Optional) Makes the operation conditional on whether the source
+ object’s generation does not match the given value.
+
+
+ * **if_source_metageneration_match** (*long*) – (Optional) Makes the operation conditional on whether the source
+ object’s current metageneration matches the given value.
+
+
+ * **if_source_metageneration_not_match** (*long*) – (Optional) Makes the operation conditional on whether the source
+ object’s current metageneration does not match the given value.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+* **Return type**
+
+ [tuple](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)
+
+
+
+* **Returns**
+
+ `(token, bytes_rewritten, total_bytes)`, where `token`
+ is a rewrite token (`None` if the rewrite is complete),
+ `bytes_rewritten` is the number of bytes rewritten so far,
+ and `total_bytes` is the total number of bytes to be
+ rewritten.
+
+
+
+#### _property_ self_link()
+Retrieve the URI for the object.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+* **Returns**
+
+ The self link for the blob or `None` if the blob’s
+ resource has not been loaded from the server.
+
+
+
+#### set_iam_policy(policy, client=None, timeout=60, retry=)
+Update the IAM policy for the bucket.
+
+**NOTE**: Blob- / object-level IAM support does not yet exist and methods
+currently call an internal ACL backend not providing any utility
+beyond the blob’s `acl` at this time. The API may be enhanced
+in the future and is currently undocumented. Use `acl` for
+managing object access control.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **policy** ([`google.api_core.iam.Policy`](https://googleapis.dev/python/google-api-core/latest/iam.html#google.api_core.iam.Policy)) – policy instance used to update bucket’s IAM policy.
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the current bucket.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+* **Return type**
+
+ [`google.api_core.iam.Policy`](https://googleapis.dev/python/google-api-core/latest/iam.html#google.api_core.iam.Policy)
+
+
+
+* **Returns**
+
+ the policy instance, based on the resource returned from
+ the `setIamPolicy` API request.
+
+
+
+#### _property_ size()
+Size of the object, in bytes.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ int or `NoneType`
+
+
+
+* **Returns**
+
+ The size of the blob or `None` if the blob’s
+ resource has not been loaded from the server.
+
+
+
+#### _property_ storage_class()
+Retrieve the storage class for the object.
+
+This can only be set at blob / object **creation** time. If you’d
+like to change the storage class **after** the blob / object already
+exists in a bucket, call `update_storage_class()` (which uses
+`rewrite()`).
+
+See [https://cloud.google.com/storage/docs/storage-classes](https://cloud.google.com/storage/docs/storage-classes)
+
+
+* **Return type**
+
+ str or `NoneType`
+
+
+
+* **Returns**
+
+ If set, one of
+ [`STANDARD_STORAGE_CLASS`](constants.md#google.cloud.storage.constants.STANDARD_STORAGE_CLASS),
+ [`NEARLINE_STORAGE_CLASS`](constants.md#google.cloud.storage.constants.NEARLINE_STORAGE_CLASS),
+ [`COLDLINE_STORAGE_CLASS`](constants.md#google.cloud.storage.constants.COLDLINE_STORAGE_CLASS),
+ [`ARCHIVE_STORAGE_CLASS`](constants.md#google.cloud.storage.constants.ARCHIVE_STORAGE_CLASS),
+ [`MULTI_REGIONAL_LEGACY_STORAGE_CLASS`](constants.md#google.cloud.storage.constants.MULTI_REGIONAL_LEGACY_STORAGE_CLASS),
+ [`REGIONAL_LEGACY_STORAGE_CLASS`](constants.md#google.cloud.storage.constants.REGIONAL_LEGACY_STORAGE_CLASS),
+ `DURABLE_REDUCED_AVAILABILITY_STORAGE_CLASS`,
+ else `None`.
+
+
+
+#### _property_ temporary_hold()
+Is a temporary hold active on the object?
+
+See [API reference docs]([https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)).
+
+If the property is not set locally, returns [`None`](https://python.readthedocs.io/en/latest/library/constants.html#None).
+
+
+* **Return type**
+
+ bool or `NoneType`
+
+
+
+#### test_iam_permissions(permissions, client=None, timeout=60, retry=)
+API call: test permissions
+
+**NOTE**: Blob- / object-level IAM support does not yet exist and methods
+currently call an internal ACL backend not providing any utility
+beyond the blob’s `acl` at this time. The API may be enhanced
+in the future and is currently undocumented. Use `acl` for
+managing object access control.
+
+If `user_project` is set on the bucket, bills the API request
+to that project.
+
+
+* **Parameters**
+
+
+ * **permissions** (*list of string*) – the permissions to check
+
+
+ * **client** ([`Client`](client.md#google.cloud.storage.client.Client)) – (Optional) The client to use. If not passed, falls back to the
+ `client` stored on the current bucket.
+
+
+ * **timeout** ([*float*](https://python.readthedocs.io/en/latest/library/functions.html#float)* or *[*tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait
+ for the server response. See: [Configuring Timeouts](retry_timeout.md#configuring-timeouts)
+
+
+ * **retry** ([*google.api_core.retry.Retry*](https://googleapis.dev/python/google-api-core/latest/retry.html#google.api_core.retry.Retry)* or *[*google.cloud.storage.retry.ConditionalRetryPolicy*](retry.md#google.cloud.storage.retry.ConditionalRetryPolicy)) – (Optional) How to retry the RPC. See: [Configuring Retries](retry_timeout.md#configuring-retries)
+
+
+
+* **Return type**
+
+ list of string
+
+
+
+* **Returns**
+
+ the permissions returned by the `testIamPermissions` API
+ request.
+
+
+
+#### _property_ time_created()
+Retrieve the timestamp at which the object was created.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ [`datetime.datetime`](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.datetime) or `NoneType`
+
+
+
+* **Returns**
+
+ Datetime object parsed from RFC3339 valid timestamp, or
+ `None` if the blob’s resource has not been loaded from
+ the server (see `reload()`).
+
+
+
+#### _property_ time_deleted()
+Retrieve the timestamp at which the object was deleted.
+
+See [https://cloud.google.com/storage/docs/json_api/v1/objects](https://cloud.google.com/storage/docs/json_api/v1/objects)
+
+
+* **Return type**
+
+ [`datetime.datetime`](https://python.readthedocs.io/en/latest/library/datetime.html#datetime.datetime) or `NoneType`
+
+
+
+* **Returns**
+
+ Datetime object parsed from RFC3339 valid timestamp, or
+ `None` if the blob’s resource has not been loaded from
+ the server (see `reload()`). If the blob has
+ not been deleted, this will never be set.
+
+
+
+#### update(client=None, if_generation_match=None, if_generation_not_match=None, if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=