Unstable

Because sometime documenting a function is unstable is not enough.

Because often, reaching to the documentation to know if something is stable takes too much time.

Because once it's stable, you'll forget to re-check again.

Installation

$ pip install unstable

Utility

This module provides a decorator to mark function as unstable. Unstable function will raise an UnstableWarningunless used in an unstable context. Thus preventing you from using an unstable function by mistake.

Provide an with unstable() context manger which silence (or log) the exceptions raised by unstable functions. By default an unstable context manager that does not detect any use of unstable functions will log a StableWarning.

See Readme for more information.

Usage

Mark a function as unstable

from unstable import unstable

@unstable
def frobulate(frumious, bandersnatch):
    galumphing(frumious) + bandersnatch

Mark a branch as being unstable

from unstable import unstable

def galumphing(frumious):
    if frumious:
        unstable.here_be_dragons(reason='frumious=True')
        # ...
    else:
        # ...

Using unstable code

By default unstable code will raise an UnstableWarning, wrap unstable code in an unstable context manager.

from unstable import unstable

with unstable:
    fumious(True, 25) # Will Behave

frumious(False, 18) # will Fail with UnstableWarning

galumphing(False) # fine

with unstable:
    galumphing(True) # fine

Context manager or decorator ?

Q : Is unstable a context manager or decorator ? A : Both. It's magic.

Advance usage:

I need to write the doc, PR welcome.

Why ?

Inspired by Rust's #[Unstable], which allows you to use it only explicitly (and I'm not talking about safety here). This mimick it (as much as it can).

I want to be able to "ship" unstable code and N.x version of a library and tell users "Use at your own risk", though no-one read the doc. Here it make things obvious, don't use it unless you meant to. Also the "instability" in contagious as function using unstable functions will become (partially) unstable. The instability boundary is obvious, it's the context manager.

What about try/except ?

It will/can catch the exception, though the called function will not run.

Todo

Add a plugin for sphinx which automatically mark the function in the doc as unstable.