Skip to main content


Project description


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

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

Mark a branch as being unstable

from unstable import unstable

def galumphing(frumious):
    if frumious:
        # ...
        # ...

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.


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for unstable, version 0.5.1
Filename, size File type Python version Upload date Hashes
Filename, size unstable-0.5.1-py3-none-any.whl (74.5 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page