Add optional valiotlogging dependency

Author: barucAlmaguer

CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## [3.5.3] - 2025-03-20
+
+- [Added] Support for valiotlogging via optional dependency
+- [Improved] Replaced print statements with structured logging
+- [Added] Custom logger functionality
+- [Improved] Added automatic traceback printing for ERROR level logs
+
 ## [3.5.2] - 2025-03-19
 
 - [Fixed] Reduce print statements in the library

README.md

@@ -16,6 +16,7 @@ Repo for the project: https://github.com/valiot/pygqlc
 - IPv4/IPv6 network flexibility
 - Intelligent error handling and reporting
 - Easy-to-use API with minimal boilerplate
+- Optional structured logging with valiotlogging
 
 ### Installation
 
@@ -38,6 +39,28 @@ $ >> print(pygqlc.name)
 
 If you get "pygqlc" printed in the python repl, the installation succeded!
 
+#### Optional: Enhanced Logging with valiotlogging
+
+If you're using this library in a Valiot project, you can install it with the valiotlogging dependency for enhanced structured logging:
+
+```
+pip install pygqlc[valiotlogging]
+```
+
+Or in your pyproject.toml:
+
+```toml
+[tool.poetry.dependencies]
+pygqlc = {version = "^3.5.3", extras = ["valiotlogging"]}
+
+[[tool.poetry.source]]
+name = "valiot"
+url = "https://pypi.valiot.io/"
+priority = "supplemental"
+```
+
+The library will automatically use valiotlogging if available, and will fall back to standard logging if not.
+
 ### Usage
 
 ```python
@@ -257,6 +280,24 @@ gql.addEnvironment(
 
 This can resolve connectivity issues in networks with suboptimal IPv6 configurations.
 
+### Custom Logging
+
+You can customize the logging behavior of pygqlc by using the `set_logger` function:
+
+```python
+from pygqlc.logging import set_logger, LogLevel
+
+# Example: Create a custom logger that writes to a file
+def my_custom_logger(level, message, extra=None):
+    with open('pygqlc.log', 'a') as f:
+        f.write(f"[{level.value}] {message}\n")
+
+# Set the custom logger
+set_logger(my_custom_logger)
+```
+
+The default logger will use valiotlogging if available, otherwise it will use a simple print-based logger.
+
 ### for mantainers:
 
 #### Initial configuration
@@ -355,9 +396,10 @@ if __name__ == "__main__":
 ```
 
 The async methods are:
+
 - `async_execute`: Low-level method to execute GraphQL operations
 - `async_query`: For GraphQL queries
 - `async_query_one`: For queries that return a single item
 - `async_mutate`: For GraphQL mutations
 
-These methods can be used with `await` in async functions and provide the same functionality as their synchronous counterparts, but with the benefits of asynchronous execution.
+These methods can be used with `await` in async functions and provide the same functionality as their synchronous counterparts, but with the benefits of asynchronous execution.

poetry.lock

@@ -16,6 +16,7 @@
 import orjson
 import logging
 from pygqlc.helper_modules.Singleton import Singleton
+from pygqlc.logging import log, LogLevel
 from tenacity import (
     retry,
     retry_if_result,
@@ -417,7 +418,7 @@ def subscribe(
         # ! initialize websocket only once
         if not self._conn:
             if not self._new_conn():
-                print('Error creating WSS connection for subscription')
+                log(LogLevel.ERROR, 'Error creating WSS connection for subscription')
                 return None
 
         _cb = callback if callback is not None else self._on_message
@@ -446,21 +447,20 @@ def unsubscribe():
     def _unsubscribe(self, _id):
         sub = self.subs.get(_id)
         if not sub:
-            print('Subscription already cleared')
+            log(LogLevel.INFO, 'Subscription already cleared')
             return
         self.unsubscribing = True
         sub['kill'] = True
         try:
             self._stop(_id)
         except BrokenPipeError as e:
-            print('WSS Pipe broken, nothing to stop')
-            print(f'original message: {e}')
+            log(LogLevel.WARNING, 'WSS Pipe broken, nothing to stop')
         sub['thread'].join()
         sub['running'] = False
         self.unsubscribing = False
 
     def _sub_routing_loop(self):
-        print('first subscription, starting routing loop')
+        log(LogLevel.INFO, 'first subscription, starting routing loop')
         last_reconnect_attempt = 0
         reconnect_delay = 1.0
 
@@ -469,13 +469,13 @@ def _sub_routing_loop(self):
                 # Rate limit reconnection attempts
                 current_time = time.time()
                 if current_time - last_reconnect_attempt >= reconnect_delay:
-                    print('Connection halted, attempting reconnection...')
+                    log(LogLevel.INFO, 'Connection halted, attempting reconnection...')
                     if self._new_conn():
                         self.wss_conn_halted = False
-                        print(
+                        log(LogLevel.INFO,
                             'WSS Reconnection succeeded, attempting resubscription to lost subs')
                         self._resubscribe_all()
-                        print('finished resubscriptions')
+                        log(LogLevel.INFO, 'finished resubscriptions')
                         reconnect_delay = 1.0  # Reset delay on success
                     else:
                         # Use exponential backoff for reconnection attempts (up to 5 seconds)
@@ -513,8 +513,7 @@ def _sub_routing_loop(self):
                 continue
             except Exception as e:
                 if not self.closing:
-                    print(f'Some error trying to receive WSS')
-                    print(f'original message: {e}')
+                    log(LogLevel.ERROR, 'Some error trying to receive WSS')
                     self.wss_conn_halted = True
                 continue
 
@@ -533,7 +532,7 @@ def _sub_routing_loop(self):
             elif message_type == PONG_TYPE:
                 pass
             else:
-                print(f'unknown msg type: {message}')
+                log(LogLevel.WARNING, f'unknown msg type: {message}')
 
             # Use non-blocking sleep
             time.sleep(self.poll_interval)
@@ -575,7 +574,8 @@ def _subscription_loop(self, _cb, _id, _ecb):
         self.subs[_id].update({'running': True, 'starting': False})
         while self.subs[_id]['running']:
             if self.subs[_id]['kill']:
-                print(f'stopping subscription id={_id} on Unsubscribe')
+                log(LogLevel.INFO,
+                    f'stopping subscription id={_id} on Unsubscribe')
                 break
 
             # Get message without copying the queue
@@ -591,22 +591,24 @@ def _subscription_loop(self, _cb, _id, _ecb):
             elif message_type == ERROR_TYPE:
                 if _ecb:
                     _ecb(message)
-                print(f'stopping subscription id={_id} on {message_type}')
+                log(LogLevel.WARNING,
+                    f'stopping subscription id={_id} on {message_type}')
                 break
             elif message_type == COMPLETE_TYPE:
-                print(f'stopping subscription id={_id} on {message_type}')
+                log(LogLevel.INFO,
+                    f'stopping subscription id={_id} on {message_type}')
                 break
             else:
-                print(f'unknown msg type: {message}')
+                log(LogLevel.WARNING, f'unknown msg type: {message}')
                 continue
 
             # Payload handling
             if is_ws_payloadErrors_msg(message):
                 if _ecb:
                     _ecb(message)
                     continue
-                print('Subscription message has payload Errors')
-                print(message)
+                log(LogLevel.ERROR, 'Subscription message has payload Errors')
+                log(LogLevel.ERROR, f'{message}')
             elif is_ws_connection_init_msg(message):
                 # Subscription successfully initialized
                 pass
@@ -617,19 +619,21 @@ def _subscription_loop(self, _cb, _id, _ecb):
                     _cb(gql_msg)  # execute callback function
                     # Increment counter without locking
                     self.subs[_id]['runs'] += 1
-                except Exception as e:
-                    print(f'Error on subscription callback: {e}')
+                except Exception as _e:
+                    log(LogLevel.ERROR, f'Error on subscription callback')
                     sub_query = self.subs[_id].get('query')
                     sub_variables = self.subs[_id].get('variables')
                     if sub_query:
-                        print(f'subscription document: \n\t{sub_query}')
+                        log(LogLevel.ERROR,
+                            f'subscription document: \n\t{sub_query}')
                     if sub_variables:
-                        print(f'subscription variables: \n\t{sub_variables}')
-                    print(traceback.format_exc())
+                        log(LogLevel.ERROR,
+                            f'subscription variables: \n\t{sub_variables}')
+                    log(LogLevel.ERROR, traceback.format_exc())
 
         # Subscription stopped, update state atomically
         self.subs[_id].update({'running': False, 'kill': True})
-        print(f'Subscription id={_id} stopped')
+        log(LogLevel.INFO, f'Subscription id={_id} stopped')
 
     def _clean_sub_message(self, _id, message):
         data = py_.get(message, 'payload', {})
@@ -644,8 +648,7 @@ def _new_conn(self):
             self._conn_init()
             return True
         except Exception as e:
-            print(f'Failed connecting to {self.ws_url}')
-            print(f'original message: {e}')
+            log(LogLevel.ERROR, f'Failed connecting to {self.ws_url}')
             return False
 
     def close(self):
@@ -655,7 +658,7 @@ def close(self):
         # ! ask subscription message router to stop
         self.closing = True
         if not self.sub_router_thread:
-            print('connection not stablished, nothing to close')
+            log(LogLevel.INFO, 'connection not stablished, nothing to close')
             self.closing = False
             return
         for sub in self.subs.values():
@@ -721,8 +724,8 @@ def _ping_pong(self):
                     # No need to log normal ping operations
                 except Exception as e:
                     if not self.closing:
-                        print('error trying to send ping, WSS Pipe is broken')
-                        print(f'original message: {e}')
+                        log(LogLevel.ERROR,
+                            'error trying to send ping, WSS Pipe is broken')
                         self.wss_conn_halted = True
 
     def _registerSub(self, _id=None):
@@ -747,19 +750,20 @@ def resetSubsConnection(self):
             (boolean): Returns if the reconnection has been possible.
         """
         if not self.sub_router_thread:
-            print('connection not stablished, nothing to reset')
+            log(LogLevel.INFO, 'connection not stablished, nothing to reset')
             return False
         if self.sub_router_thread.is_alive():  # check that _sub_routing_loop() is running
             self._conn.close()  # forces connection halted (wss_conn_halted)
             return True
         # in case for some reason _sub_routing_loop() is not running
         if self._new_conn():
-            print('WSS Reconnection succeeded, attempting resubscription to lost subs')
+            log(LogLevel.INFO,
+                'WSS Reconnection succeeded, attempting resubscription to lost subs')
             self._resubscribe_all()
-            print('finished resubscriptions')
+            log(LogLevel.INFO, 'finished resubscriptions')
             return True
         else:
-            print('Reconnection has not been possible')
+            log(LogLevel.ERROR, 'Reconnection has not been possible')
             return False
 
     # * END SUBSCRIPTION functions ******************************
@@ -1210,7 +1214,8 @@ async def async_cleanup(self):
                         await self._async_client.aclose()
             except Exception as e:  # pylint: disable=broad-except
                 # If closing fails, log but continue
-                print(f"Warning: Error closing async client: {str(e)}")
+                log(LogLevel.WARNING,
+                    f"Warning: Error closing async client: {str(e)}")
             finally:
                 # Always set to None to allow garbage collection and recreation
                 self._async_client = None

pygqlc/GraphQLClient.py

@@ -1,3 +1,4 @@
+from .__version__ import __version__
 from .GraphQLClient import GraphQLClient, GQLResponseException
 from .QueryParser import QueryParser
 from .MutationParser import MutationParser
@@ -6,5 +7,3 @@
 
 # * Package name:
 name = 'pygqlc'
-
-from .__version__ import __version__

pygqlc/__init__.py

@@ -1 +1 @@
-__version__ = '3.5.2'
+__version__ = '3.5.3'