Skip to content

Commit

Permalink
Improve references in the main docstrings (#131)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Kludex
Kludex authored May 6, 2024
1 parent d6ca2c4 commit d3c2767
Showing 1 changed file with 40 additions and 27 deletions.
67 changes: 40 additions & 27 deletions logfire/_internal/main.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -218,9 +218,10 @@ def trace(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
"""
if any(k.startswith('_') for k in attributes):
raise ValueError('Attribute keys cannot start with an underscore.')
Expand All @@ -247,9 +248,10 @@ def debug(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
"""
if any(k.startswith('_') for k in attributes):
raise ValueError('Attribute keys cannot start with an underscore.')
Expand All @@ -276,9 +278,10 @@ def info(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
"""
if any(k.startswith('_') for k in attributes):
raise ValueError('Attribute keys cannot start with an underscore.')
Expand All @@ -305,9 +308,10 @@ def notice(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
"""
if any(k.startswith('_') for k in attributes):
raise ValueError('Attribute keys cannot start with an underscore.')
Expand All @@ -334,9 +338,10 @@ def warn(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
"""
if any(k.startswith('_') for k in attributes):
raise ValueError('Attribute keys cannot start with an underscore.')
Expand All @@ -363,9 +368,10 @@ def error(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
"""
if any(k.startswith('_') for k in attributes):
raise ValueError('Attribute keys cannot start with an underscore.')
Expand All @@ -392,9 +398,10 @@ def fatal(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
"""
if any(k.startswith('_') for k in attributes):
raise ValueError('Attribute keys cannot start with an underscore.')
Expand All @@ -417,7 +424,7 @@ def exception(
msg_template: The message to log.
attributes: The attributes to bind to the log.
_tags: An optional sequence of tags to include in the log.
_exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
_exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
"""
if any(k.startswith('_') for k in attributes): # pragma: no cover
Expand Down Expand Up @@ -450,7 +457,6 @@ def span(
_tags: An optional sequence of tags to include in the span.
_level: An optional log level name.
_stack_offset: The stack level offset to use when collecting stack info, defaults to `3`.
attributes: The arguments to include in the span and format the message template with.
Attributes starting with an underscore are not allowed.
"""
Expand Down Expand Up @@ -519,16 +525,20 @@ def log(
msg_template: The message to log.
attributes: The attributes to bind to the log.
tags: An optional sequence of tags to include in the log.
exc_info: Set to an exception or a tuple as returned by `sys.exc_info()`
exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
to record a traceback with the log message.
Set to True to use the currently handled exception.
Set to `True` to use the currently handled exception.
stack_offset: The stack level offset to use when collecting stack info, also affects the warning which
message formatting might emit, defaults to `0` which means the stack info will be collected from the
position where `logfire.log` was called.
position where [`logfire.log`][logfire.Logfire.log] was called.
console_log: Whether to log to the console, defaults to `True`.
custom_scope_suffix: A custom suffix to append to `logfire.`, should only be used when you're using
logfire to instrument another library like structlog or loguru.
See `TraceProvider.get_tracer(instrumenting_module_name)` docstring for more info.
custom_scope_suffix: A custom suffix to append to `logfire.` e.g. `logfire.loguru`.
It should only be used when instrumenting another library with Logfire, such as structlog or loguru.
See the `instrumenting_module_name` parameter on
[TracerProvider.get_tracer][opentelemetry.sdk.trace.TracerProvider.get_tracer] for more info.
"""
stack_offset = (self._stack_offset if stack_offset is None else stack_offset) + 2
stack_info = get_caller_stack_info(stack_offset)
Expand Down Expand Up @@ -639,11 +649,14 @@ def with_settings(
tags: Sequence of tags to include in the log.
stack_offset: The stack level offset to use when collecting stack info, also affects the warning which
message formatting might emit, defaults to `0` which means the stack info will be collected from the
position where `logfire.log` was called.
position where [`logfire.log`][logfire.Logfire.log] was called.
console_log: Whether to log to the console, defaults to `True`.
custom_scope_suffix: A custom suffix to append to `logfire.`, should only be used when you're using
logfire to instrument another library like structlog or loguru.
See `TraceProvider.get_tracer(instrumenting_module_name)` docstring for more info.
custom_scope_suffix: A custom suffix to append to `logfire.` e.g. `logfire.loguru`.
It should only be used when instrumenting another library with Logfire, such as structlog or loguru.
See the `instrumenting_module_name` parameter on
[TracerProvider.get_tracer][opentelemetry.sdk.trace.TracerProvider.get_tracer] for more info.
Returns:
A new Logfire instance with the given settings applied.
Expand Down Expand Up @@ -1081,7 +1094,7 @@ def shutdown(self, timeout_millis: int = 30_000, flush: bool = True) -> bool: #
flush: Whether to flush remaining spans and metrics before shutting down.
Returns:
False if the timeout was reached before the shutdown was completed, True otherwise.
`False` if the timeout was reached before the shutdown was completed, `True` otherwise.
"""
start = time()
if flush: # pragma: no branch
Expand Down

0 comments on commit d3c2767

Please sign in to comment.