Fix bad warning placement, update docs

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.16](https://github.com/wesky93/grpc_requests/releases/tag/v0.1.16) - 2024-03-03
+
+## Added
+
+- Additional usage examples
+
+## Fixed
+
+- Put deprecation warnings in the correct place for old get_descriptor methods, so they do not warn at all times.
+
 ## [0.1.15](https://github.com/wesky93/grpc_requests/releases/tag/v0.1.15) - 2024-02-17
 
 ## Added

src/examples/README.md

@@ -147,6 +147,23 @@ helloworldFileDescriptors = client.get_file_descriptors_by_name("helloworld.prot
 greeterServiceFileDescriptors = client.get_file_descriptors_by_symbol("helloworld.Greeter")
 ```
 
+### Registering Descriptors Directly
+
+In the event a message is utilized by a service, but not directly referenced
+by the typing in the reflected service (i.e. a specific type of metadata served
+by a service implementing a [longrunning operation](https://google.aip.dev/151)), that message can
+be added directly as follows:
+
+```python
+from grpc_requests.client import Client
+
+from grpc_requests.client import Client
+
+client = Client("localhost:50051")
+
+hiddenMessageFileDescriptors = client.get_file_descriptors_by_name("hiddenMessage.proto")
+```
+
 ### Method Metadata
 
 grpc_requests utilizes MethodMetaData objects to organize the methods of the

src/grpc_requests/__init__.py

@@ -7,4 +7,4 @@
 )
 from .client import Client, ReflectionClient, StubClient, get_by_endpoint
 
-__version__ = "0.1.15"
+__version__ = "0.1.16"

src/grpc_requests/aio.py

@@ -453,23 +453,21 @@ async def _get_service_names(self):
         services = tuple([s.name for s in resp.list_services_response.service])
         return services
 
-    warnings.warn(
-        "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_name() instead.",
-        DeprecationWarning,
-    )
-
     async def get_file_descriptor_by_name(self, name):
+        warnings.warn(
+            "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_name() instead.",
+            DeprecationWarning,
+        )
         request = reflection_pb2.ServerReflectionRequest(file_by_filename=name)
         result = await self._reflection_single_request(request)
         proto = result.file_descriptor_response.file_descriptor_proto[0]
         return descriptor_pb2.FileDescriptorProto.FromString(proto)
 
-    warnings.warn(
-        "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_symbol() instead.",
-        DeprecationWarning,
-    )
-
     async def get_file_descriptor_by_symbol(self, symbol):
+        warnings.warn(
+            "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_symbol() instead.",
+            DeprecationWarning,
+        )
         request = reflection_pb2.ServerReflectionRequest(file_containing_symbol=symbol)
         result = await self._reflection_single_request(request)
         proto = result.file_descriptor_response.file_descriptor_proto[0]
@@ -499,10 +497,15 @@ def _is_descriptor_registered(self, filename):
         except KeyError:
             return False
 
-    # Iterate over descriptors for registration, including returned descriptors as possible dependencies.
-    # This is necessary as while in practice descriptors appear to be returned in an order that works for dependency
-    # registration, this is not guaranteed in the reflection specification.
-    async def register_file_descriptors(self, file_descriptors):
+    async def register_file_descriptors(
+        self, file_descriptors: List[descriptor_pb2.FileDescriptorProto]
+    ):
+        """
+        Iterate over descriptors for registration, including returned descriptors as possible dependencies.
+        This is necessary as while in practice descriptors appear to be returned in an order that works for dependency
+        registration, this is not guaranteed in the reflection specification.
+        :param file_descriptors: List of FileDescriptorProto to register
+        """
         for file_descriptor in file_descriptors:
             await self._register_file_descriptor(file_descriptor, file_descriptors)
 

src/grpc_requests/client.py

@@ -472,23 +472,21 @@ def _get_service_names(self):
         services = tuple([s.name for s in resp.list_services_response.service])
         return services
 
-    warnings.warn(
-        "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_name() instead.",
-        DeprecationWarning,
-    )
-
     def get_file_descriptor_by_name(self, name):
+        warnings.warn(
+            "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_name() instead.",
+            DeprecationWarning,
+        )
         request = reflection_pb2.ServerReflectionRequest(file_by_filename=name)
         result = self._reflection_single_request(request)
         proto = result.file_descriptor_response.file_descriptor_proto[0]
         return descriptor_pb2.FileDescriptorProto.FromString(proto)
 
-    warnings.warn(
-        "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_symbol() instead.",
-        DeprecationWarning,
-    )
-
     def get_file_descriptor_by_symbol(self, symbol):
+        warnings.warn(
+            "This function is deprecated, and will be removed in the 0.1.17 release. Use get_file_descriptors_by_symbol() instead.",
+            DeprecationWarning,
+        )
         request = reflection_pb2.ServerReflectionRequest(file_containing_symbol=symbol)
         result = self._reflection_single_request(request)
         proto = result.file_descriptor_response.file_descriptor_proto[0]
@@ -518,10 +516,15 @@ def _is_descriptor_registered(self, filename):
         except KeyError:
             return False
 
-    # Iterate over descriptors for registration, including returned descriptors as possible dependencies.
-    # This is necessary as while in practice descriptors appear to be returned in an order that works for dependency
-    # registration, this is not guaranteed in the reflection specification.
-    def register_file_descriptors(self, file_descriptors):
+    def register_file_descriptors(
+        self, file_descriptors: List[descriptor_pb2.FileDescriptorProto]
+    ):
+        """
+        Iterate over descriptors for registration, including returned descriptors as possible dependencies.
+        This is necessary as while in practice descriptors appear to be returned in an order that works for dependency
+        registration, this is not guaranteed in the reflection specification.
+        :param file_descriptors: List of FileDescriptorProto to register
+        """
         for file_descriptor in file_descriptors:
             self._register_file_descriptor(file_descriptor, file_descriptors)