Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve references in the main docstrings #131

Merged
merged 1 commit into from
May 6, 2024
Merged

Improve references in the main docstrings #131

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 40 additions & 27 deletions logfire/_internal/main.py
View file
Open in desktop
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