Metadata-Version: 1.2
Name: unstable
Version: 0.5.1
Summary: Unstable
Home-page: https://github.com/Carreau/unstable
License: UNKNOWN
Author: Matthias Bussonnier
Author-email: bussonniermatthias@gmail.com
Requires-Python: >=3
Classifier: License :: OSI Approved :: BSD License

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 ``UnstableWarning``\ unless 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
---------------------------

.. code:: python

    from unstable import unstable

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

Mark a branch as being unstable
-------------------------------

.. code:: python

    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.

.. code:: python

    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.

