Skip to content

Commit

Permalink
It's args and kwargs
Browse files Browse the repository at this point in the history
  • Loading branch information
@hynek
hynek committed Dec 29, 2023
1 parent 9767d82 commit d3150de
Show file tree
Hide file tree
Showing 14 changed files with 54 additions and 99 deletions.
8 changes: 3 additions & 5 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,13 +128,11 @@ But it's way more comfortable to run it locally and catch avoidable errors befor
"""
Do something.
Parameters:
x: A very important parameter.
Args:
x: A very important parameter.
Returns:
A very important return value.
A very important return value.
"""
```
- If you add or change public APIs, tag the docstring using `.. versionadded:: 16.0.0 WHAT` or `.. versionchanged:: 16.2.0 WHAT`.
Expand Down
14 changes: 3 additions & 11 deletions src/structlog/_base.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,6 @@ def unbind(self, *keys: str) -> BoundLoggerBase:
Return a new logger with *keys* removed from the context.
Raises:
KeyError: If the key is not part of the context.
"""
bl = self.bind()
Expand Down Expand Up @@ -123,8 +122,7 @@ def _process_event(
Call it to combine your *event* and *context* into an event_dict and
process using the processor chain.
Parameters:
Args:
method_name:
The name of the logger method. Is passed into the processors.
Expand All @@ -137,7 +135,6 @@ def _process_event(
*event_kw* ``{"bar": 42}``.
Raises:
structlog.DropEvent: if log entry should be dropped.
ValueError:
Expand All @@ -148,7 +145,6 @@ def _process_event(
`tuple` of ``(*args, **kw)``
.. note::
Despite underscore available to custom wrapper classes.
See also `custom-wrappers`.
Expand Down Expand Up @@ -197,8 +193,7 @@ def _proxy_to_logger(
handling :exc:`structlog.DropEvent`, and finally calls *method_name* on
:attr:`_logger` with the result.
Parameters:
Args:
method_name:
The name of the method that's going to get called. Technically
it should be identical to the method the user called because it
Expand All @@ -213,7 +208,6 @@ def _proxy_to_logger(
*event_kw* ``{"bar": 42}``.
.. note::
Despite underscore available to custom wrapper classes.
See also `custom-wrappers`.
Expand All @@ -232,12 +226,10 @@ def get_context(bound_logger: BindableLogger) -> Context:
The type of *bound_logger* and the type returned depend on your
configuration.
Parameters:
Args:
bound_logger: The bound logger whose context you want.
Returns:
The *actual* context from *bound_logger*. It is *not* copied first.
.. versionadded:: 20.2.0
Expand Down
12 changes: 3 additions & 9 deletions src/structlog/_config.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -114,8 +114,7 @@ def get_logger(*args: Any, **initial_values: Any) -> Any:
>>> log.info("hello", x=42)
y=23 x=42 event='hello'
Parameters:
Args:
args:
*Optional* positional arguments that are passed unmodified to the
logger factory. Therefore it depends on the factory what they
Expand All @@ -124,7 +123,6 @@ def get_logger(*args: Any, **initial_values: Any) -> Any:
initial_values: Values that are used to pre-populate your contexts.
Returns:
A proxy that creates a correctly configured bound logger when
necessary. The type of that bound logger depends on your configuration
and is `structlog.BoundLogger` by default.
Expand Down Expand Up @@ -169,16 +167,14 @@ def wrap_logger(
In other words: selective overwriting of the defaults while keeping some
*is* possible.
Parameters:
Args:
initial_values: Values that are used to pre-populate your contexts.
logger_factory_args:
Values that are passed unmodified as ``*logger_factory_args`` to
the logger factory if not `None`.
Returns:
A proxy that creates a correctly configured bound logger when
necessary.
Expand Down Expand Up @@ -217,8 +213,7 @@ def configure(
Use `reset_defaults` to undo your changes.
Parameters:
Args:
processors: The processor chain. See :doc:`processors` for details.
wrapper_class:
Expand Down Expand Up @@ -269,7 +264,6 @@ def configure_once(
`configure_once` before.
Raises:
RuntimeWarning: if repeated configuration is attempted.
"""
if not _CONFIG.is_configured:
Expand Down
3 changes: 1 addition & 2 deletions src/structlog/_log_levels.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,8 +139,7 @@ def make_filtering_bound_logger(min_level: int) -> type[FilteringBoundLogger]:
- You *can* have (much) more fine-grained filtering by :ref:`writing a
simple processor <finer-filtering>`.
Parameters:
Args:
min_level:
The log level as an integer. You can use the constants from
`logging` like ``logging.INFO`` or pass the values directly. See
Expand Down
17 changes: 6 additions & 11 deletions src/structlog/_output.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,7 @@ class PrintLogger:
"""
Print events into a file.
Parameters:
Args:
file: File to print to. (default: `sys.stdout`)
>>> from structlog import PrintLogger
Expand Down Expand Up @@ -122,8 +121,7 @@ class PrintLoggerFactory:
To be used with `structlog.configure`\ 's ``logger_factory``.
Parameters:
Args:
file: File to print to. (default: `sys.stdout`)
Positional arguments are silently ignored.
Expand All @@ -142,8 +140,7 @@ class WriteLogger:
"""
Write events into a file.
Parameters:
Args:
file: File to print to. (default: `sys.stdout`)
>>> from structlog import WriteLogger
Expand Down Expand Up @@ -232,8 +229,7 @@ class WriteLoggerFactory:
To be used with `structlog.configure`\ 's ``logger_factory``.
Parameters:
Args:
file: File to print to. (default: `sys.stdout`)
Positional arguments are silently ignored.
Expand All @@ -252,7 +248,7 @@ class BytesLogger:
r"""
Writes bytes into a file.
Parameters:
Args:
file: File to print to. (default: `sys.stdout`\ ``.buffer``)
Useful if you follow `current logging best practices
Expand Down Expand Up @@ -336,8 +332,7 @@ class BytesLoggerFactory:
To be used with `structlog.configure`\ 's ``logger_factory``.
Parameters:
Args:
file: File to print to. (default: `sys.stdout`\ ``.buffer``)
Positional arguments are silently ignored.
Expand Down
15 changes: 11 additions & 4 deletions src/structlog/_utils.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,27 @@
import sys

from contextlib import suppress
from typing import Any, Callable
from typing import Any, Callable, TypeVar


def until_not_interrupted(f: Callable[..., Any], *args: Any, **kw: Any) -> Any:
T = TypeVar("T")


def until_not_interrupted(
f: Callable[..., T], *args: object, **kw: object
) -> T:
"""
Retry until *f* succeeds or an exception that isn't caused by EINTR occurs.
Parameters:
Args:
f: A callable like a function.
*args: Positional arguments for *f*.
**kw: Keyword arguments for *f*.
Returns:
Whatever *f* returns.
"""
while True:
try:
Expand Down
34 changes: 11 additions & 23 deletions src/structlog/processors.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,7 @@ class KeyValueRenderer:
"""
Render ``event_dict`` as a list of ``Key=repr(Value)`` pairs.
Parameters:
Args:
sort_keys: Whether to sort keys when formatting.
key_order:
Expand Down Expand Up @@ -119,8 +118,7 @@ class LogfmtRenderer:
.. _logfmt: https://brandur.org/logfmt
Parameters:
Args:
sort_keys: Whether to sort keys when formatting.
key_order:
Expand All @@ -138,7 +136,6 @@ class LogfmtRenderer:
``flag=false``.
Raises:
ValueError: If a key contains non printable or space characters.
.. versionadded:: 21.5.0
Expand Down Expand Up @@ -237,8 +234,7 @@ class UnicodeEncoder:
"""
Encode unicode values in ``event_dict``.
Parameters:
Args:
encoding: Encoding to encode to (default: ``"utf-8"``).
errors:
Expand Down Expand Up @@ -272,8 +268,7 @@ class UnicodeDecoder:
"""
Decode byte string values in ``event_dict``.
Parameters:
Args:
encoding: Encoding to decode from (default: ``"utf-8"``).
errors: How to cope with encoding errors (default: ``"replace"``).
Expand Down Expand Up @@ -308,8 +303,7 @@ class JSONRenderer:
"""
Render the ``event_dict`` using ``serializer(event_dict, **dumps_kw)``.
Parameters:
Args:
dumps_kw:
Are passed unmodified to *serializer*. If *default* is passed, it
will disable support for ``__structlog__``-based serialization.
Expand Down Expand Up @@ -385,8 +379,7 @@ class ExceptionRenderer:
If there is no ``exc_info`` key, the *event_dict* is not touched. This
behavior is analog to the one of the stdlib's logging.
Parameters:
Args:
exception_formatter:
A callable that is used to format the exception from the
``exc_info`` field into the ``exception`` field.
Expand Down Expand Up @@ -459,8 +452,7 @@ class TimeStamper:
"""
Add a timestamp to ``event_dict``.
Parameters:
Args:
fmt:
strftime format string, or ``"iso"`` for `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_, or `None` for a `UNIX
Expand Down Expand Up @@ -608,8 +600,7 @@ class ExceptionPrettyPrinter:
"""
Pretty print exceptions and remove them from the ``event_dict``.
Parameters:
Args:
file: Target file for output (default: ``sys.stdout``).
This processor is mostly for development and testing so you can read
Expand Down Expand Up @@ -661,8 +652,7 @@ class StackInfoRenderer:
involving an exception and works analogously to the *stack_info* argument
of the Python standard library logging.
Parameters:
Args:
additional_ignores:
By default, stack frames coming from *structlog* are ignored. With
this argument you can add additional names that are ignored, before
Expand Down Expand Up @@ -745,8 +735,7 @@ class CallsiteParameterAdder:
The keys used for callsite parameters in the event dictionary are the
string values of `CallsiteParameter` enum members.
Parameters:
Args:
parameters:
A collection of `CallsiteParameter` values that should be added to
the event dictionary.
Expand Down Expand Up @@ -880,8 +869,7 @@ class EventRenamer:
some processors may rely on the presence and meaning of the ``event``
key.
Parameters:
Args:
to: Rename ``event_dict["event"]`` to ``event_dict[to]``
replace_by:
Expand Down
Loading

0 comments on commit d3150de

Please sign in to comment.