logging future warnings

[Eduardo Blancas]

whenever we have to change the API, we display a FutureWarning to users so they have a chance to update their code. However, we don't know the proportion of them that already switched.

It'd be better to log these events, so we know when users need more time to switch because we want to ship new features as fast as possible without compromising stability.

We can add a telemetry.deprecation_warning method that uses warnings.warn (with FutureWarning) and captures the event.

[Eduardo Blancas]

FYI @idomic

[Tony Kuo]

Do you mean every time we show the future warnings, meanwhile we will log the event to PostHog?

[Eduardo Blancas]

a function that will show a FutureWarning, but also log the event to posthog

[Ido M]

@tonykploomber please write an AC of what you think is expected here before starting on this.

[Tony Kuo]

Acceptance Criteria:

We want to record:

• The consumer function name of each function in src/ploomber_core/depreciated.py
  (e.g. add has @deprecated.function decorator, we need to know add was called and send to posthug

@deprecated.function(deprecated_in="0.1", remove_in="0.2")
def add(x, y):
    """
    Notes
    -----
    .. deprecated:: 0.1
        ``add`` is deprecated, will be removed in version 0.2
    """
    return x + y

• versionadded argument value
• deprecated argument value

@edublancas Let me know if this makes sense to you.
For the implementation, I guess we want to have a new method like log_deprecation_warning which similar to log_call in telemetry?

And we want to make it as the decorator function and apply it to parameter_renamed, parameter_deprecated, function, method... to collect the complete data of those calling metadata

[Eduardo Blancas]

We created the @deprecated.* decorators when we were mostly working in sklearn-evaluation. Ironically, now that we shifted to JupySQL, these decorators are not very relevant since the user interacts with JupySQL via the %sql magic, instead of importing and calling regular Python functions. So what I'm proposing is something simpler like this:

from warnings import warn

def deprecation_warning(message):
    warn(message, FutureWarning)
    # also log the event to posthog

Then, if in JupySQL we want to deprecate %sql --some-argument, we can do:

if args.some_argument is not None:
    deprecation_warning("--some argument has been deprecated")

Later, we can decide if we also add posthog calls to the @deprecated decorators, but for now, we don't have to.