google-developer-knowledge 0.1.0__py3-none-any.whl

google/developer_knowledge_v1/services/developer_knowledge/transports/rest_base.py

@@ -0,0 +1,236 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 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 json  # type: ignore
+import re
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple, Union
+
+from google.api_core import gapic_v1, path_template
+from google.protobuf import json_format
+
+from google.developer_knowledge_v1.types import developerknowledge
+
+from .base import DEFAULT_CLIENT_INFO, DeveloperKnowledgeTransport
+
+
+class _BaseDeveloperKnowledgeRestTransport(DeveloperKnowledgeTransport):
+    """Base REST backend transport for DeveloperKnowledge.
+
+    Note: This class is not meant to be used directly. Use its sync and
+    async sub-classes instead.
+
+    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 JSON representations of protocol buffers over HTTP/1.1
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str = "developerknowledge.googleapis.com",
+        credentials: Optional[Any] = None,
+        client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
+        always_use_jwt_access: Optional[bool] = False,
+        url_scheme: str = "https",
+        api_audience: Optional[str] = None,
+    ) -> None:
+        """Instantiate the transport.
+        Args:
+            host (Optional[str]):
+                 The hostname to connect to (default: 'developerknowledge.googleapis.com').
+            credentials (Optional[Any]): 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.
+            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 are developing
+                your own client library.
+            always_use_jwt_access (Optional[bool]): Whether self signed JWT should
+                be used for service account credentials.
+            url_scheme: the protocol scheme for the API endpoint.  Normally
+                "https", but for testing or local servers,
+                "http" can be specified.
+        """
+        # Run the base constructor
+        maybe_url_match = re.match("^(?P<scheme>http(?:s)?://)?(?P<host>.*)$", host)
+        if maybe_url_match is None:
+            raise ValueError(
+                f"Unexpected hostname structure: {host}"
+            )  # pragma: NO COVER
+
+        url_match_items = maybe_url_match.groupdict()
+
+        host = f"{url_scheme}://{host}" if not url_match_items["scheme"] else host
+
+        super().__init__(
+            host=host,
+            credentials=credentials,
+            client_info=client_info,
+            always_use_jwt_access=always_use_jwt_access,
+            api_audience=api_audience,
+        )
+
+    class _BaseBatchGetDocuments:
+        def __hash__(self):  # pragma: NO COVER
+            return NotImplementedError("__hash__ must be implemented.")
+
+        __REQUIRED_FIELDS_DEFAULT_VALUES: Dict[str, Any] = {
+            "names": "",
+        }
+
+        @classmethod
+        def _get_unset_required_fields(cls, message_dict):
+            return {
+                k: v
+                for k, v in cls.__REQUIRED_FIELDS_DEFAULT_VALUES.items()
+                if k not in message_dict
+            }
+
+        @staticmethod
+        def _get_http_options():
+            http_options: List[Dict[str, str]] = [
+                {
+                    "method": "get",
+                    "uri": "/v1/documents:batchGet",
+                },
+            ]
+            return http_options
+
+        @staticmethod
+        def _get_transcoded_request(http_options, request):
+            pb_request = developerknowledge.BatchGetDocumentsRequest.pb(request)
+            transcoded_request = path_template.transcode(http_options, pb_request)
+            return transcoded_request
+
+        @staticmethod
+        def _get_query_params_json(transcoded_request):
+            query_params = json.loads(
+                json_format.MessageToJson(
+                    transcoded_request["query_params"],
+                    use_integers_for_enums=True,
+                )
+            )
+            query_params.update(
+                _BaseDeveloperKnowledgeRestTransport._BaseBatchGetDocuments._get_unset_required_fields(
+                    query_params
+                )
+            )
+
+            query_params["$alt"] = "json;enum-encoding=int"
+            return query_params
+
+    class _BaseGetDocument:
+        def __hash__(self):  # pragma: NO COVER
+            return NotImplementedError("__hash__ must be implemented.")
+
+        __REQUIRED_FIELDS_DEFAULT_VALUES: Dict[str, Any] = {}
+
+        @classmethod
+        def _get_unset_required_fields(cls, message_dict):
+            return {
+                k: v
+                for k, v in cls.__REQUIRED_FIELDS_DEFAULT_VALUES.items()
+                if k not in message_dict
+            }
+
+        @staticmethod
+        def _get_http_options():
+            http_options: List[Dict[str, str]] = [
+                {
+                    "method": "get",
+                    "uri": "/v1/{name=documents/**}",
+                },
+            ]
+            return http_options
+
+        @staticmethod
+        def _get_transcoded_request(http_options, request):
+            pb_request = developerknowledge.GetDocumentRequest.pb(request)
+            transcoded_request = path_template.transcode(http_options, pb_request)
+            return transcoded_request
+
+        @staticmethod
+        def _get_query_params_json(transcoded_request):
+            query_params = json.loads(
+                json_format.MessageToJson(
+                    transcoded_request["query_params"],
+                    use_integers_for_enums=True,
+                )
+            )
+            query_params.update(
+                _BaseDeveloperKnowledgeRestTransport._BaseGetDocument._get_unset_required_fields(
+                    query_params
+                )
+            )
+
+            query_params["$alt"] = "json;enum-encoding=int"
+            return query_params
+
+    class _BaseSearchDocumentChunks:
+        def __hash__(self):  # pragma: NO COVER
+            return NotImplementedError("__hash__ must be implemented.")
+
+        __REQUIRED_FIELDS_DEFAULT_VALUES: Dict[str, Any] = {
+            "query": "",
+        }
+
+        @classmethod
+        def _get_unset_required_fields(cls, message_dict):
+            return {
+                k: v
+                for k, v in cls.__REQUIRED_FIELDS_DEFAULT_VALUES.items()
+                if k not in message_dict
+            }
+
+        @staticmethod
+        def _get_http_options():
+            http_options: List[Dict[str, str]] = [
+                {
+                    "method": "get",
+                    "uri": "/v1/documents:searchDocumentChunks",
+                },
+            ]
+            return http_options
+
+        @staticmethod
+        def _get_transcoded_request(http_options, request):
+            pb_request = developerknowledge.SearchDocumentChunksRequest.pb(request)
+            transcoded_request = path_template.transcode(http_options, pb_request)
+            return transcoded_request
+
+        @staticmethod
+        def _get_query_params_json(transcoded_request):
+            query_params = json.loads(
+                json_format.MessageToJson(
+                    transcoded_request["query_params"],
+                    use_integers_for_enums=True,
+                )
+            )
+            query_params.update(
+                _BaseDeveloperKnowledgeRestTransport._BaseSearchDocumentChunks._get_unset_required_fields(
+                    query_params
+                )
+            )
+
+            query_params["$alt"] = "json;enum-encoding=int"
+            return query_params
+
+
+__all__ = ("_BaseDeveloperKnowledgeRestTransport",)

google/developer_knowledge_v1/types/__init__.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 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 .developerknowledge import (
+    BatchGetDocumentsRequest,
+    BatchGetDocumentsResponse,
+    Document,
+    DocumentChunk,
+    DocumentView,
+    GetDocumentRequest,
+    SearchDocumentChunksRequest,
+    SearchDocumentChunksResponse,
+)
+
+__all__ = (
+    "BatchGetDocumentsRequest",
+    "BatchGetDocumentsResponse",
+    "Document",
+    "DocumentChunk",
+    "GetDocumentRequest",
+    "SearchDocumentChunksRequest",
+    "SearchDocumentChunksResponse",
+    "DocumentView",
+)

google/developer_knowledge_v1/types/developerknowledge.py

@@ -0,0 +1,413 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 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 __future__ import annotations
+
+from typing import MutableMapping, MutableSequence
+
+import google.protobuf.timestamp_pb2 as timestamp_pb2  # type: ignore
+import proto  # type: ignore
+
+__protobuf__ = proto.module(
+    package="google.developers.knowledge.v1",
+    manifest={
+        "DocumentView",
+        "Document",
+        "SearchDocumentChunksRequest",
+        "SearchDocumentChunksResponse",
+        "GetDocumentRequest",
+        "BatchGetDocumentsRequest",
+        "BatchGetDocumentsResponse",
+        "DocumentChunk",
+    },
+)
+
+
+class DocumentView(proto.Enum):
+    r"""Specifies which fields of the
+    [Document][google.developers.knowledge.v1.Document] are included.
+
+    Values:
+        DOCUMENT_VIEW_UNSPECIFIED (0):
+            The default / unset value. See each API method for its
+            default value if
+            [DocumentView][google.developers.knowledge.v1.DocumentView]
+            is not specified.
+        DOCUMENT_VIEW_BASIC (1):
+            Includes only the basic metadata fields:
+
+            - ``name``
+            - ``uri``
+            - ``data_source``
+            - ``title``
+            - ``description``
+            - ``update_time``
+            - ``view``
+
+            This is the default of view for
+            [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1.DeveloperKnowledge.SearchDocumentChunks].
+        DOCUMENT_VIEW_FULL (2):
+            Includes all
+            [Document][google.developers.knowledge.v1.Document] fields.
+        DOCUMENT_VIEW_CONTENT (3):
+            Includes the ``DOCUMENT_VIEW_BASIC`` fields and the
+            ``content`` field.
+
+            This is the default of view for
+            [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1.DeveloperKnowledge.GetDocument]
+            and
+            [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments].
+    """
+
+    DOCUMENT_VIEW_UNSPECIFIED = 0
+    DOCUMENT_VIEW_BASIC = 1
+    DOCUMENT_VIEW_FULL = 2
+    DOCUMENT_VIEW_CONTENT = 3
+
+
+class Document(proto.Message):
+    r"""A Document represents a piece of content from the Developer
+    Knowledge corpus.
+
+    Attributes:
+        name (str):
+            Identifier. Contains the resource name of the document.
+            Format: ``documents/{uri_without_scheme}`` Example:
+            ``documents/docs.cloud.google.com/storage/docs/creating-buckets``
+        uri (str):
+            Output only. Provides the URI of the content, such as
+            ``docs.cloud.google.com/storage/docs/creating-buckets``.
+        content (str):
+            Output only. Contains the full content of the
+            document in Markdown format.
+        description (str):
+            Output only. Provides a description of the
+            document.
+        data_source (str):
+            Output only. Specifies the data source of the document.
+            Example data source: ``firebase.google.com``
+        title (str):
+            Output only. Provides the title of the
+            document.
+        update_time (google.protobuf.timestamp_pb2.Timestamp):
+            Output only. Represents the timestamp when
+            the content or metadata of the document was last
+            updated.
+        view (google.developer_knowledge_v1.types.DocumentView):
+            Output only. Specifies the
+            [DocumentView][google.developers.knowledge.v1.DocumentView]
+            of the document.
+    """
+
+    name: str = proto.Field(
+        proto.STRING,
+        number=1,
+    )
+    uri: str = proto.Field(
+        proto.STRING,
+        number=2,
+    )
+    content: str = proto.Field(
+        proto.STRING,
+        number=3,
+    )
+    description: str = proto.Field(
+        proto.STRING,
+        number=4,
+    )
+    data_source: str = proto.Field(
+        proto.STRING,
+        number=5,
+    )
+    title: str = proto.Field(
+        proto.STRING,
+        number=6,
+    )
+    update_time: timestamp_pb2.Timestamp = proto.Field(
+        proto.MESSAGE,
+        number=7,
+        message=timestamp_pb2.Timestamp,
+    )
+    view: "DocumentView" = proto.Field(
+        proto.ENUM,
+        number=8,
+        enum="DocumentView",
+    )
+
+
+class SearchDocumentChunksRequest(proto.Message):
+    r"""Request message for
+    [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1.DeveloperKnowledge.SearchDocumentChunks].
+
+    Attributes:
+        query (str):
+            Required. Provides the raw query string
+            provided by the user, such as "How to create a
+            Cloud Storage bucket?".
+        page_size (int):
+            Optional. Specifies the maximum number of results to return.
+            The service may return fewer than this value.
+
+            If unspecified, at most 5 results will be returned.
+
+            The maximum value is 20; values above 20 will result in an
+            INVALID_ARGUMENT error.
+        page_token (str):
+            Optional. Contains a page token, received from a previous
+            ``SearchDocumentChunks`` call. Provide this to retrieve the
+            subsequent page.
+        filter (str):
+            Optional. Applies a strict filter to the search results. The
+            expression supports a subset of the syntax described at
+            https://google.aip.dev/160.
+
+            While ``SearchDocumentChunks`` returns
+            [DocumentChunk][google.developers.knowledge.v1.DocumentChunk]s,
+            the filter is applied to ``DocumentChunk.document`` fields.
+
+            Supported fields for filtering:
+
+            - ``data_source`` (STRING): The source of the document, e.g.
+              ``docs.cloud.google.com``. See
+              https://developers.google.com/knowledge/reference/corpus-reference
+              for the complete list of data sources in the corpus.
+            - ``update_time`` (TIMESTAMP): The timestamp of when the
+              document was last meaningfully updated. A meaningful
+              update is one that changes document's markdown content or
+              metadata.
+            - ``uri`` (STRING): The document URI, e.g.
+              ``https://docs.cloud.google.com/bigquery/docs/tables``.
+
+            STRING fields support ``=`` (equals) and ``!=`` (not equals)
+            operators for **exact match** on the whole string. Partial
+            match, prefix match, and regexp match are not supported.
+
+            TIMESTAMP fields support ``=``, ``<``, ``<=``, ``>``, and
+            ``>=`` operators. Timestamps must be in RFC-3339 format,
+            e.g., ``"2025-01-01T00:00:00Z"``.
+
+            You can combine expressions using ``AND``, ``OR``, and
+            ``NOT`` (or ``-``) logical operators. ``OR`` has higher
+            precedence than ``AND``. Use parentheses for explicit
+            precedence grouping.
+
+            Examples:
+
+            - ``data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"``
+            - ``data_source != "firebase.google.com"``
+            - ``update_time < "2024-01-01T00:00:00Z"``
+            - ``update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")``
+            - ``uri = "https://docs.cloud.google.com/release-notes"``
+
+            The ``filter`` string must not exceed 500 characters; values
+            longer than 500 characters will result in an
+            ``INVALID_ARGUMENT`` error.
+    """
+
+    query: str = proto.Field(
+        proto.STRING,
+        number=1,
+    )
+    page_size: int = proto.Field(
+        proto.INT32,
+        number=2,
+    )
+    page_token: str = proto.Field(
+        proto.STRING,
+        number=3,
+    )
+    filter: str = proto.Field(
+        proto.STRING,
+        number=4,
+    )
+
+
+class SearchDocumentChunksResponse(proto.Message):
+    r"""Response message for
+    [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1.DeveloperKnowledge.SearchDocumentChunks].
+
+    Attributes:
+        results (MutableSequence[google.developer_knowledge_v1.types.DocumentChunk]):
+            Contains the search results for the given query. Each
+            [DocumentChunk][google.developers.knowledge.v1.DocumentChunk]
+            in this list contains a snippet of content relevant to the
+            search query. Use the
+            [DocumentChunk.parent][google.developers.knowledge.v1.DocumentChunk.parent]
+            field of each result with
+            [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1.DeveloperKnowledge.GetDocument]
+            or
+            [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments]
+            to retrieve the full document content.
+        next_page_token (str):
+            Optional. Provides a token that can be sent as
+            ``page_token`` to retrieve the next page. If this field is
+            omitted, there are no subsequent pages.
+    """
+
+    @property
+    def raw_page(self):
+        return self
+
+    results: MutableSequence["DocumentChunk"] = proto.RepeatedField(
+        proto.MESSAGE,
+        number=1,
+        message="DocumentChunk",
+    )
+    next_page_token: str = proto.Field(
+        proto.STRING,
+        number=2,
+    )
+
+
+class GetDocumentRequest(proto.Message):
+    r"""Request message for
+    [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1.DeveloperKnowledge.GetDocument].
+
+    Attributes:
+        name (str):
+            Required. Specifies the name of the document to retrieve.
+            Format: ``documents/{uri_without_scheme}`` Example:
+            ``documents/docs.cloud.google.com/storage/docs/creating-buckets``
+        view (google.developer_knowledge_v1.types.DocumentView):
+            Optional. Specifies the
+            [DocumentView][google.developers.knowledge.v1.DocumentView]
+            of the document. If unspecified,
+            [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1.DeveloperKnowledge.GetDocument]
+            defaults to ``DOCUMENT_VIEW_CONTENT``.
+    """
+
+    name: str = proto.Field(
+        proto.STRING,
+        number=1,
+    )
+    view: "DocumentView" = proto.Field(
+        proto.ENUM,
+        number=2,
+        enum="DocumentView",
+    )
+
+
+class BatchGetDocumentsRequest(proto.Message):
+    r"""Request message for
+    [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments].
+
+    Attributes:
+        names (MutableSequence[str]):
+            Required. Specifies the names of the documents to retrieve.
+            A maximum of 20 documents can be retrieved in a batch. The
+            documents are returned in the same order as the ``names`` in
+            the request.
+
+            Format: ``documents/{uri_without_scheme}`` Example:
+            ``documents/docs.cloud.google.com/storage/docs/creating-buckets``
+        view (google.developer_knowledge_v1.types.DocumentView):
+            Optional. Specifies the
+            [DocumentView][google.developers.knowledge.v1.DocumentView]
+            of the document. If unspecified,
+            [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments]
+            defaults to ``DOCUMENT_VIEW_CONTENT``.
+    """
+
+    names: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=1,
+    )
+    view: "DocumentView" = proto.Field(
+        proto.ENUM,
+        number=2,
+        enum="DocumentView",
+    )
+
+
+class BatchGetDocumentsResponse(proto.Message):
+    r"""Response message for
+    [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments].
+
+    Attributes:
+        documents (MutableSequence[google.developer_knowledge_v1.types.Document]):
+            Contains the documents requested.
+    """
+
+    documents: MutableSequence["Document"] = proto.RepeatedField(
+        proto.MESSAGE,
+        number=1,
+        message="Document",
+    )
+
+
+class DocumentChunk(proto.Message):
+    r"""A DocumentChunk represents a piece of content from a
+    [Document][google.developers.knowledge.v1.Document] in the
+    DeveloperKnowledge corpus. To fetch the entire document content,
+    pass the ``parent`` to
+    [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1.DeveloperKnowledge.GetDocument]
+    or
+    [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments].
+
+    Attributes:
+        parent (str):
+            Output only. Contains the resource name of the document this
+            chunk is from. Format: ``documents/{uri_without_scheme}``
+            Example:
+            ``documents/docs.cloud.google.com/storage/docs/creating-buckets``
+        id (str):
+            Output only. Specifies the ID of this chunk
+            within the document. The chunk ID is unique
+            within a document, but not globally unique
+            across documents. The chunk ID is not stable and
+            may change over time.
+        content (str):
+            Output only. Contains the content of the
+            document chunk.
+        document (google.developer_knowledge_v1.types.Document):
+            Output only. Represents metadata about the
+            [Document][google.developers.knowledge.v1.Document] this
+            chunk is from. The
+            [DocumentView][google.developers.knowledge.v1.DocumentView]
+            of this [Document][google.developers.knowledge.v1.Document]
+            message will be set to ``DOCUMENT_VIEW_BASIC``. It is
+            included here for convenience so that clients do not need to
+            call
+            [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1.DeveloperKnowledge.GetDocument]
+            or
+            [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments]
+            if they only need the metadata fields. Otherwise, clients
+            should use
+            [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1.DeveloperKnowledge.GetDocument]
+            or
+            [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1.DeveloperKnowledge.BatchGetDocuments]
+            to fetch the full document content.
+    """
+
+    parent: str = proto.Field(
+        proto.STRING,
+        number=1,
+    )
+    id: str = proto.Field(
+        proto.STRING,
+        number=2,
+    )
+    content: str = proto.Field(
+        proto.STRING,
+        number=3,
+    )
+    document: "Document" = proto.Field(
+        proto.MESSAGE,
+        number=4,
+        message="Document",
+    )
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))