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.
$ pip install unstable
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.
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.
I need to write the doc, PR welcome.
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.
Add a plugin for sphinx which automatically mark the function in the doc as unstable.