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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Carreau/unstable",
"name": "unstable",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "",
"author": "Matthias Bussonnier",
"author_email": "bussonniermatthias@gmail.com",
"download_url": "",
"platform": "",
"description": "Unstable\n========\n\nBecause sometime documenting a function is unstable is not enough.\n\nBecause often, reaching to the documentation to know if something is\nstable takes too much time.\n\nBecause once it's stable, you'll forget to re-check again.\n\nInstallation\n============\n\n::\n\n $ pip install unstable\n\nUtility\n=======\n\nThis module provides a decorator to mark function as ``unstable``.\nUnstable function will **raise** an ``UnstableWarning``\\ unless used in\nan ``unstable`` context. Thus preventing you from using an unstable\nfunction by mistake.\n\nProvide an ``with unstable()`` context manger which silence (or log) the\nexceptions raised by unstable functions. By default an ``unstable``\ncontext manager that does not detect any use of ``unstable`` functions\nwill log a ``StableWarning``.\n\nSee Readme for more information.\n\nUsage\n=====\n\nMark a function as unstable\n---------------------------\n\n.. code:: python\n\n from unstable import unstable\n\n @unstable\n def frobulate(frumious, bandersnatch):\n galumphing(frumious) + bandersnatch\n\nMark a branch as being unstable\n-------------------------------\n\n.. code:: python\n\n from unstable import unstable\n\n def galumphing(frumious):\n if frumious:\n unstable.here_be_dragons(reason='frumious=True')\n # ...\n else:\n # ...\n\nUsing unstable code\n-------------------\n\nBy default unstable code will raise an ``UnstableWarning``, wrap\nunstable code in an ``unstable`` context manager.\n\n.. code:: python\n\n from unstable import unstable\n\n with unstable:\n fumious(True, 25) # Will Behave\n\n frumious(False, 18) # will Fail with UnstableWarning\n\n galumphing(False) # fine\n\n with unstable:\n galumphing(True) # fine\n\nContext manager or decorator ?\n==============================\n\nQ : Is unstable a context manager or decorator ? A : Both. It's magic.\n\nAdvance usage:\n==============\n\nI need to write the doc, PR welcome.\n\nWhy ?\n=====\n\nInspired by Rust's ``#[Unstable]``, which allows you to use it only\nexplicitly (and I'm not talking about safety here). This mimick it (as\nmuch as it can).\n\nI want to be able to \"ship\" unstable code and N.x version of a library\nand tell users \"Use at your own risk\", though no-one read the doc. Here\nit make things obvious, don't use it unless you **meant** to. Also the\n\"instability\" in contagious as function using unstable functions will\nbecome (partially) unstable. The instability boundary is obvious, it's\nthe context manager.\n\nWhat about try/except ?\n-----------------------\n\nIt will/can catch the exception, though the called function will not\nrun.\n\nTodo\n====\n\nAdd a plugin for sphinx which automatically mark the function in the doc\nas unstable.\n",
"bugtrack_url": null,
"license": "",
"summary": "Unstable",
"version": "0.5.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "7dfd9fc8464274869f1e49f7cd106fcf",
"sha256": "331c29b1bcb9521cb4319957d1493563b1d0a8f289e53a6fe6bd45e3d3bf261e"
},
"downloads": -1,
"filename": "unstable-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7dfd9fc8464274869f1e49f7cd106fcf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 74452,
"upload_time": "2017-01-31T02:47:06",
"upload_time_iso_8601": "2017-01-31T02:47:06.304714Z",
"url": "https://files.pythonhosted.org/packages/80/2b/08592d9bf22f536bea640b7828e5f7b817190c9e22f0b8305ffb82cf48df/unstable-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2017-01-31 02:47:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Carreau",
"github_project": "unstable",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "unstable"
}
JSON
