logxpy 0.1.0__py3-none-any.whl

logxpy/_generators.py

@@ -0,0 +1,136 @@
+"""
+Support for maintaining an action context across generator suspension.
+"""
+
+from sys import exc_info
+from functools import wraps
+from contextlib import contextmanager
+from contextvars import copy_context
+from weakref import WeakKeyDictionary
+
+from . import log_message
+
+
+class _GeneratorContext(object):
+    """Generator sub-context for C{_ExecutionContext}."""
+
+    def __init__(self, execution_context):
+        self._execution_context = execution_context
+        self._contexts = WeakKeyDictionary()
+        self._current_generator = None
+
+    def init_stack(self, generator):
+        """Create a new stack for the given generator."""
+        self._contexts[generator] = copy_context()
+
+    @contextmanager
+    def in_generator(self, generator):
+        """Context manager: set the given generator as the current generator."""
+        previous_generator = self._current_generator
+        try:
+            self._current_generator = generator
+            yield
+        finally:
+            self._current_generator = previous_generator
+
+
+class GeneratorSupportNotEnabled(Exception):
+    """
+    An attempt was made to use a decorated generator without first turning on
+    the generator context manager.
+    """
+
+
+def eliot_friendly_generator_function(original):
+    """
+    Decorate a generator function so that the Eliot action context is
+    preserved across ``yield`` expressions.
+    """
+
+    @wraps(original)
+    def wrapper(*a, **kw):
+        # Keep track of whether the next value to deliver to the generator is
+        # a non-exception or an exception.
+        ok = True
+
+        # Keep track of the next value to deliver to the generator.
+        value_in = None
+
+        # Create the generator with a call to the generator function.  This
+        # happens with whatever Eliot action context happens to be active,
+        # which is fine and correct and also irrelevant because no code in the
+        # generator function can run until we call send or throw on it.
+        gen = original(*a, **kw)
+
+        # Initialize the per-generator context to a copy of the current context.
+        context = copy_context()
+        while True:
+            try:
+                # Whichever way we invoke the generator, we will do it
+                # with the Eliot action context stack we've saved for it.
+                # Then the context manager will re-save it and restore the
+                # "outside" stack for us.
+                #
+                # Regarding the support of Twisted's inlineCallbacks-like
+                # functionality (see eliot.twisted.inline_callbacks):
+                #
+                # The invocation may raise the inlineCallbacks internal
+                # control flow exception _DefGen_Return.  It is not wrong to
+                # just let that propagate upwards here but inlineCallbacks
+                # does think it is wrong.  The behavior triggers a
+                # DeprecationWarning to try to get us to fix our code.  We
+                # could explicitly handle and re-raise the _DefGen_Return but
+                # only at the expense of depending on a private Twisted API.
+                # For now, I'm opting to try to encourage Twisted to fix the
+                # situation (or at least not worsen it):
+                # https://twistedmatrix.com/trac/ticket/9590
+                #
+                # Alternatively, _DefGen_Return is only required on Python 2.
+                # When Python 2 support is dropped, this concern can be
+                # eliminated by always using `return value` instead of
+                # `returnValue(value)` (and adding the necessary logic to the
+                # StopIteration handler below).
+                def go():
+                    if ok:
+                        value_out = gen.send(value_in)
+                    else:
+                        value_out = gen.throw(*value_in)
+                    # We have obtained a value from the generator.  In
+                    # giving it to us, it has given up control.  Note this
+                    # fact here.  Importantly, this is within the
+                    # generator's action context so that we get a good
+                    # indication of where the yield occurred.
+                    #
+                    # This is noisy, enable only for debugging:
+                    if wrapper.debug:
+                        log_message(message_type="yielded")
+                    return value_out
+
+                value_out = context.run(go)
+            except StopIteration:
+                # When the generator raises this, it is signaling
+                # completion.  Leave the loop.
+                break
+            else:
+                try:
+                    # Pass the generator's result along to whoever is
+                    # driving.  Capture the result as the next value to
+                    # send inward.
+                    value_in = yield value_out
+                except:
+                    # Or capture the exception if that's the flavor of the
+                    # next value.  This could possibly include GeneratorExit
+                    # which turns out to be just fine because throwing it into
+                    # the inner generator effectively propagates the close
+                    # (and with the right context!) just as you would want.
+                    # True, the GeneratorExit does get re-throwing out of the
+                    # gen.throw call and hits _the_generator_context's
+                    # contextmanager.  But @contextmanager extremely
+                    # conveniently eats it for us!  Thanks, @contextmanager!
+                    ok = False
+                    value_in = exc_info()
+                else:
+                    ok = True
+
+    wrapper.debug = False
+    return wrapper

logxpy/_mask.py

@@ -0,0 +1,23 @@
+"""Field masking."""
+from __future__ import annotations
+import re
+from typing import Any
+
+class Masker:
+    def __init__(self, fields: list[str], patterns: list[str]):
+        self._fields = {f.lower() for f in fields}
+        self._patterns = [re.compile(p) for p in patterns]
+    
+    def mask(self, data: dict[str, Any]) -> dict[str, Any]:
+        return {k: self._mask(k, v) for k, v in data.items()}
+    
+    def _mask(self, key: str, val: Any) -> Any:
+        if key.lower() in self._fields: return "***"
+        if isinstance(val, str):
+            for p in self._patterns:
+                val = p.sub("***", val)
+        elif isinstance(val, dict):
+            return self.mask(val)
+        elif isinstance(val, list):
+            return [self._mask(key, v) for v in val]
+        return val

logxpy/_message.py

@@ -0,0 +1,195 @@
+"""
+Log messages and related utilities.
+"""
+
+import time
+from warnings import warn
+
+from pyrsistent import PClass, pmap_field
+
+MESSAGE_TYPE_FIELD = "message_type"
+TASK_UUID_FIELD = "task_uuid"
+TASK_LEVEL_FIELD = "task_level"
+TIMESTAMP_FIELD = "timestamp"
+
+EXCEPTION_FIELD = "exception"
+REASON_FIELD = "reason"
+
+
+class Message(object):
+    """
+    A log message.
+
+    Messages are basically dictionaries, mapping "fields" to "values". Field
+    names should not start with C{'_'}, as those are reserved for system use
+    (e.g. C{"_id"} is used by Elasticsearch for unique message identifiers and
+    may be auto-populated by logstash).
+    """
+
+    # Overrideable for testing purposes:
+    _time = time.time
+
+    @classmethod
+    def new(_class, _serializer=None, **fields):
+        """
+        Create a new L{Message}.
+
+        The keyword arguments will become the initial contents of the L{Message}.
+
+        @param _serializer: A positional argument, either C{None} or a
+            L{eliot._validation._MessageSerializer} with which a
+            L{eliot.ILogger} may choose to serialize the message. If you're
+            using L{eliot.MessageType} this will be populated for you.
+
+        @return: The new L{Message}
+        """
+        warn(
+            "Message.new() is deprecated since 1.11.0, "
+            "use eliot.log_message() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _class(fields, _serializer)
+
+    @classmethod
+    def log(_class, **fields):
+        """
+        Write a new L{Message} to the default L{Logger}.
+
+        The keyword arguments will become contents of the L{Message}.
+        """
+        warn(
+            "Message.log() is deprecated since 1.11.0, "
+            "use Action.log() or eliot.log_message() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        _class(fields).write()
+
+    def __init__(self, contents, serializer=None):
+        """
+        You can also use L{Message.new} to create L{Message} objects.
+
+        @param contents: The contents of this L{Message}, a C{dict} whose keys
+           must be C{str}, or text that has been UTF-8 encoded to
+           C{bytes}.
+
+        @param serializer: Either C{None}, or
+            L{eliot._validation._MessageSerializer} with which a
+            L{eliot.Logger} may choose to serialize the message. If you're
+            using L{eliot.MessageType} this will be populated for you.
+        """
+        self._contents = contents.copy()
+        self._serializer = serializer
+
+    def bind(self, **fields):
+        """
+        Return a new L{Message} with this message's contents plus the
+        additional given bindings.
+        """
+        contents = self._contents.copy()
+        contents.update(fields)
+        return Message(contents, self._serializer)
+
+    def contents(self):
+        """
+        Return a copy of L{Message} contents.
+        """
+        return self._contents.copy()
+
+    def _timestamp(self):
+        """
+        Return the current time.
+        """
+        return self._time()
+
+    def write(self, logger=None, action=None):
+        """
+        Write the message to the given logger.
+
+        This will additionally include a timestamp, the action context if any,
+        and any other fields.
+
+        Byte field names will be converted to Unicode.
+
+        @type logger: L{eliot.ILogger} or C{None} indicating the default one.
+            Should not be set if the action is also set.
+
+        @param action: The L{Action} which is the context for this message.  If
+            C{None}, the L{Action} will be deduced from the current call stack.
+        """
+        fields = dict(self._contents)
+        if "message_type" not in fields:
+            fields["message_type"] = ""
+        if self._serializer is not None:
+            fields["__eliot_serializer__"] = self._serializer
+        if action is None:
+            if logger is not None:
+                fields["__eliot_logger__"] = logger
+            log_message(**fields)
+        else:
+            action.log(**fields)
+
+
+class WrittenMessage(PClass):
+    """
+    A L{Message} that has been logged.
+
+    @ivar _logged_dict: The originally logged dictionary.
+    """
+
+    _logged_dict = pmap_field((str, str), object)
+
+    @property
+    def timestamp(self):
+        """
+        The Unix timestamp of when the message was logged.
+        """
+        return self._logged_dict[TIMESTAMP_FIELD]
+
+    @property
+    def task_uuid(self):
+        """
+        The UUID of the task in which the message was logged.
+        """
+        return self._logged_dict[TASK_UUID_FIELD]
+
+    @property
+    def task_level(self):
+        """
+        The L{TaskLevel} of this message appears within the task.
+        """
+        return TaskLevel(level=self._logged_dict[TASK_LEVEL_FIELD])
+
+    @property
+    def contents(self):
+        """
+        A C{PMap}, the message contents without Eliot metadata.
+        """
+        return (
+            self._logged_dict.discard(TIMESTAMP_FIELD)
+            .discard(TASK_UUID_FIELD)
+            .discard(TASK_LEVEL_FIELD)
+        )
+
+    @classmethod
+    def from_dict(cls, logged_dictionary):
+        """
+        Reconstruct a L{WrittenMessage} from a logged dictionary.
+
+        @param logged_dictionary: A C{PMap} representing a parsed log entry.
+        @return: A L{WrittenMessage} for that dictionary.
+        """
+        return cls(_logged_dict=logged_dictionary)
+
+    def as_dict(self):
+        """
+        Return the dictionary that was used to write this message.
+
+        @return: A C{dict}, as might be logged by Eliot.
+        """
+        return self._logged_dict
+
+
+# Import at end to deal with circular imports:
+from ._action import log_message, TaskLevel