gapic-generator 1.30.4__py3-none-any.whl → 1.30.6__py3-none-any.whl

gapic/cli/generate.py

@@ -23,6 +23,7 @@ from google.protobuf.compiler import plugin_pb2
 from gapic import generator
 from gapic.schema import api
 from gapic.utils import Options
+from gapic.utils.cache import generation_cache_context
 
 
 @click.command()
@@ -56,15 +57,23 @@ def generate(request: typing.BinaryIO, output: typing.BinaryIO) -> None:
         [p.package for p in req.proto_file if p.name in req.file_to_generate]
     ).rstrip(".")
 
-    # Build the API model object.
-    # This object is a frozen representation of the whole API, and is sent
-    # to each template in the rendering step.
-    api_schema = api.API.build(req.proto_file, opts=opts, package=package)
+    # Create the generation cache context.
+    # This provides the shared storage for the @cached_proto_context decorator.
+    # 1. Performance: Memoizes `with_context` calls, speeding up generation significantly.
+    # 2. Safety: The decorator uses this storage to "pin" Proto objects in memory.
+    #    This prevents Python's Garbage Collector from deleting objects created during
+    #    `API.build` while `Generator.get_response` is still using their IDs.
+    #    (See `gapic.utils.cache.cached_proto_context` for the specific pinning logic).
+    with generation_cache_context():
+        # Build the API model object.
+        # This object is a frozen representation of the whole API, and is sent
+        # to each template in the rendering step.
+        api_schema = api.API.build(req.proto_file, opts=opts, package=package)
 
-    # Translate into a protobuf CodeGeneratorResponse; this reads the
-    # individual templates and renders them.
-    # If there are issues, error out appropriately.
-    res = generator.Generator(opts).get_response(api_schema, opts)
+        # Translate into a protobuf CodeGeneratorResponse; this reads the
+        # individual templates and renders them.
+        # If there are issues, error out appropriately.
+        res = generator.Generator(opts).get_response(api_schema, opts)
 
     # Output the serialized response.
     output.write(res.SerializeToString())

gapic/schema/imp.py

@@ -26,11 +26,21 @@ class Import:
         return self.package == other.package and self.module == other.module
 
     def __str__(self) -> str:
+        # Determine if we need to suppress type checking for this import.
+        # We do this for protobuf generated files (_pb2) and api_core
+        # internals where type information might be missing or incomplete.
+        needs_type_ignore = self.module.endswith("_pb2") or "api_core" in self.package
+        if needs_type_ignore:
+            # Use 'import absolute.path as module' syntax to prevent Ruff/isort
+            # from combining this with other imports. This ensures the
+            # '# type: ignore' comment remains effective for this specific import.
+            full_module = ".".join(self.package + (self.module,))
+            alias = self.alias or self.module
+            return f"import {full_module} as {alias}  # type: ignore"
+
         answer = f"import {self.module}"
         if self.package:
             answer = f"from {'.'.join(self.package)} {answer}"
         if self.alias:
             answer += f" as {self.alias}"
-        if self.module.endswith("_pb2") or "api_core" in self.package:
-            answer += "  # type: ignore"
         return answer

gapic/schema/metadata.py

@@ -35,6 +35,7 @@ from google.protobuf import descriptor_pb2
 from gapic.schema import imp
 from gapic.schema import naming
 from gapic.utils import cached_property
+from gapic.utils import cached_proto_context
 from gapic.utils import RESERVED_NAMES
 
 # This class is a minor hack to optimize Address's __eq__ method.
@@ -359,6 +360,7 @@ class Address(BaseAddress):
             return f'{".".join(self.package)}.{selector}'
         return selector
 
+    @cached_proto_context
     def with_context(self, *, collisions: Set[str]) -> "Address":
         """Return a derivative of this address with the provided context.
 
@@ -398,6 +400,7 @@ class Metadata:
             return "\n\n".join(self.documentation.leading_detached_comments)
         return ""
 
+    @cached_proto_context
     def with_context(self, *, collisions: Set[str]) -> "Metadata":
         """Return a derivative of this metadata with the provided context.
 

gapic/schema/wrappers.py

@@ -67,6 +67,7 @@ from google.protobuf.json_format import MessageToDict  # type: ignore
 
 from gapic import utils
 from gapic.schema import metadata
+from gapic.utils import cached_proto_context
 from gapic.utils import uri_sample
 from gapic.utils import make_private
 
@@ -410,6 +411,7 @@ class Field:
             "This code should not be reachable; please file a bug."
         )
 
+    @cached_proto_context
     def with_context(
         self,
         *,
@@ -805,6 +807,7 @@ class MessageType:
         # message.
         return cursor.message.get_field(*field_path[1:], collisions=collisions)
 
+    @cached_proto_context
     def with_context(
         self,
         *,
@@ -937,6 +940,7 @@ class EnumType:
         """Return the identifier data to be used in templates."""
         return self.meta.address
 
+    @cached_proto_context
     def with_context(self, *, collisions: Set[str]) -> "EnumType":
         """Return a derivative of this enum with the provided context.
 
@@ -1058,6 +1062,7 @@ class ExtendedOperationInfo:
     request_type: MessageType
     operation_type: MessageType
 
+    @cached_proto_context
     def with_context(
         self,
         *,
@@ -1127,6 +1132,7 @@ class OperationInfo:
     response_type: MessageType
     metadata_type: MessageType
 
+    @cached_proto_context
     def with_context(
         self,
         *,
@@ -1937,6 +1943,7 @@ class Method:
         """Return True if this method has no return value, False otherwise."""
         return self.output.ident.proto == "google.protobuf.Empty"
 
+    @cached_proto_context
     def with_context(
         self,
         *,
@@ -2357,6 +2364,7 @@ class Service:
     def is_internal(self) -> bool:
         return any(m.is_internal for m in self.methods.values())
 
+    @cached_proto_context
     def with_context(
         self,
         *,

gapic/templates/%namespace/%name_%version/%sub/services/%service/_shared_macros.j2

@@ -196,8 +196,9 @@ def _get_http_options():
         body_spec (str): The http options body i.e. method.http_options[0].body
         method_name (str): The method name.
         service: The service.
-        is_async (bool): Used to determine the code path i.e. whether for sync or async call. #}
-{% macro rest_call_method_common(body_spec, method_name, service, is_async=False, is_proto_plus_type=False) %}
+        is_async (bool): Used to determine the code path i.e. whether for sync or async call.
+        is_request_message_proto_plus_type (bool): Used to determine whether the request message is a proto-plus type. #}
+{% macro rest_call_method_common(body_spec, method_name, service, is_async=False, is_request_message_proto_plus_type=False) %}
 {% set service_name = service.name %}
 {% set await_prefix = "await " if is_async else "" %}
 {% set async_class_prefix = "Async" if is_async else "" %}
@@ -218,7 +219,7 @@ def _get_http_options():
         request_url = "{host}{uri}".format(host=self._host, uri=transcoded_request['uri'])
         method = transcoded_request['method']
         try:
-            request_payload = {% if is_proto_plus_type %}type(request).to_json(request){% else %}json_format.MessageToJson(request){% endif %}
+            request_payload = {% if is_request_message_proto_plus_type %}type(request).to_json(request){% else %}json_format.MessageToJson(request){% endif %}
 
         except:
             {# TODO(https://github.com/googleapis/gapic-generator-python/issues/2282): Remove try/except and correctly parse request payload. #}

gapic/templates/%namespace/%name_%version/%sub/services/%service/transports/base.py.j2

@@ -3,7 +3,7 @@
 {% block content %}
 
 import abc
-from typing import Awaitable, Callable, Dict, Optional, Sequence, Union
+from typing import {% if service.any_extended_operations_methods %}Any, {% endif %}Awaitable, Callable, Dict, Optional, Sequence, Union
 
 {% set package_path = api.naming.module_namespace|join('.') + "." + api.naming.versioned_module_name %}
 from {{package_path}} import gapic_version as package_version

gapic/templates/%namespace/%name_%version/%sub/services/%service/transports/rest.py.j2

@@ -240,7 +240,7 @@ class {{service.name}}RestTransport(_Base{{ service.name }}RestTransport):
             {% endif %}
             """
 
-            {{ shared_macros.rest_call_method_common(body_spec, method.name, service, False, method.output.ident.is_proto_plus_type)|indent(8) }}
+            {{ shared_macros.rest_call_method_common(body_spec, method.name, service, False, method.input.ident.is_proto_plus_type)|indent(8) }}
 
             {% if not method.void %}
             # Return the response

gapic/templates/%namespace/%name_%version/%sub/services/%service/transports/rest_asyncio.py.j2

@@ -202,7 +202,7 @@ class Async{{service.name}}RestTransport(_Base{{ service.name }}RestTransport):
             {% endif %}
             """
 
-            {{ shared_macros.rest_call_method_common(body_spec, method.name, service, True, method.output.ident.is_proto_plus_type)|indent(8) }}
+            {{ shared_macros.rest_call_method_common(body_spec, method.name, service, True, method.input.ident.is_proto_plus_type)|indent(8) }}
 
             {% if not method.void %}
             # Return the response

gapic/templates/docs/common_setup.py.j2

@@ -0,0 +1,35 @@
+{% macro sphinx_imports() -%}
+import logging
+from typing import Any
+{%- endmacro %}
+
+{% macro sphinx_setup() -%}
+class UnexpectedUnindentFilter(logging.Filter):
+    """Filter out warnings about unexpected unindentation following bullet lists."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Filter the log record.
+
+        Args:
+            record (logging.LogRecord): The log record.
+
+        Returns:
+            bool: False to suppress the warning, True to allow it.
+        """
+        msg = record.getMessage()
+        if "Bullet list ends without a blank line" in msg:
+            return False
+        return True
+
+
+def setup(app: Any) -> None:
+    """Setup the Sphinx application.
+
+    Args:
+        app (Any): The Sphinx application.
+    """
+    # Sphinx's logger is hierarchical. Adding a filter to the
+    # root 'sphinx' logger will catch warnings from all sub-loggers.
+    logger = logging.getLogger('sphinx')
+    logger.addFilter(UnexpectedUnindentFilter())
+{%- endmacro %}

gapic/templates/docs/conf.py.j2

@@ -1,7 +1,7 @@
 {% extends '_base.py.j2' %}
 
 {% block content %}
-
+{% from "docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %}
 #
 # {{ api.naming.warehouse_package_name }} documentation build configuration file
 #
@@ -14,9 +14,11 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
+import logging
 import os
 import shlex
+import sys
+{{ sphinx_imports() }}
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -372,4 +374,7 @@ napoleon_use_admonition_for_references = False
 napoleon_use_ivar = False
 napoleon_use_param = True
 napoleon_use_rtype = True
+
+# Setup for sphinx behaviors such as warning filters.
+{{ sphinx_setup() }}
 {% endblock %}

gapic/utils/__init__.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 from gapic.utils.cache import cached_property
+from gapic.utils.cache import cached_proto_context
 from gapic.utils.case import to_snake_case
 from gapic.utils.case import to_camel_case
 from gapic.utils.checks import is_msg_field_pb
@@ -34,6 +35,7 @@ from gapic.utils.uri_conv import convert_uri_fieldnames
 
 __all__ = (
     "cached_property",
+    "cached_proto_context",
     "convert_uri_fieldnames",
     "doc",
     "empty",

gapic/utils/cache.py

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 import functools
+import contextlib
+import threading
 
 
 def cached_property(fx):
@@ -43,3 +45,93 @@ def cached_property(fx):
         return self._cached_values[fx.__name__]
 
     return property(inner)
+
+
+# Thread-local storage for the simple cache dictionary.
+# This ensures that parallel generation tasks (if any) do not corrupt each other's cache.
+_proto_collisions_cache_state = threading.local()
+
+
+@contextlib.contextmanager
+def generation_cache_context():
+    """Context manager to explicitly manage the lifecycle of the generation cache.
+
+    This manager initializes a fresh dictionary in thread-local storage when entering
+    the context and strictly deletes it when exiting.
+
+    **Memory Management:**
+    The cache stores strong references to Proto objects to "pin" them in memory
+    (see `cached_proto_context`). It is critical that this context manager deletes
+    the dictionary in the `finally` block. Deleting the dictionary breaks the
+    reference chain, allowing Python's Garbage Collector to finally free all the
+    large Proto objects that were pinned during generation.
+    """
+    # Initialize the cache as a standard dictionary.
+    _proto_collisions_cache_state.resolved_collisions = {}
+    try:
+        yield
+    finally:
+        # Delete the dictionary to free all memory and pinned objects.
+        # This is essential to prevent memory leaks in long-running processes.
+        del _proto_collisions_cache_state.resolved_collisions
+
+
+def cached_proto_context(func):
+    """Decorator to memoize `with_context` calls based on object identity and collisions.
+
+    This mechanism provides a significant performance boost by preventing
+    redundant recalculations of naming collisions during template rendering.
+
+    Since the Proto wrapper objects are unhashable (mutable), we use `id(self)` as
+    the primary cache key. Normally, this is dangerous: if the object is garbage
+    collected, Python might reuse its memory address for a *new* object, leading to
+    a cache collision (the "Zombie ID" bug).
+
+    To prevent this, this decorator stores the value as a tuple: `(result, self)`.
+    By keeping a reference to `self` in the cache value, we "pin" the object in
+    memory. This forces the Garbage Collector to keep the object alive, guaranteeing
+    that `id(self)` remains unique for the entire lifespan of the `generation_cache_context`.
+
+    Args:
+        func (Callable): The function to decorate (usually `with_context`).
+
+    Returns:
+        Callable: The wrapped function with caching and pinning logic.
+    """
+
+    @functools.wraps(func)
+    def wrapper(self, *, collisions, **kwargs):
+
+        # 1. Check for active cache (returns None if context is not active)
+        context_cache = getattr(
+            _proto_collisions_cache_state, "resolved_collisions", None
+        )
+
+        # If we are not inside a generation_cache_context (e.g. unit tests),
+        # bypass the cache entirely.
+        if context_cache is None:
+            return func(self, collisions=collisions, **kwargs)
+
+        # 2. Create the cache key
+        # We use frozenset for collisions to make it hashable.
+        # We use id(self) because 'self' is not hashable.
+        collisions_key = frozenset(collisions) if collisions else None
+        key = (id(self), collisions_key)
+
+        # 3. Check Cache
+        if key in context_cache:
+            # The cache stores (result, pinned_object). We return just the result.
+            return context_cache[key][0]
+
+        # 4. Execute the actual function
+        # We ensure context_cache is passed down to the recursive calls
+        result = func(self, collisions=collisions, **kwargs)
+
+        # 5. Update Cache & Pin Object
+        # We store (result, self). The reference to 'self' prevents garbage collection,
+        # ensuring that 'id(self)' cannot be reused for a new object while this
+        # cache entry exists.
+        context_cache[key] = (result, self)
+        return result
+
+    return wrapper

{gapic_generator-1.30.4.dist-info → gapic_generator-1.30.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gapic-generator
-Version: 1.30.4
+Version: 1.30.6
 Summary: Google API Client Generator for Python
 Home-page: https://github.com/googleapis/gapic-generator-python
 Author: Google LLC