| Name | pvandyken-deprecated JSON |
| Version |
0.0.4
JSON |
| download |
| home_page | |
| Summary | Wrapper to manage deprecations |
| upload_time | 2023-09-20 20:41:30 |
| maintainer | |
| docs_url | None |
| author | Peter Van Dyken |
| requires_python | >=3.8 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
deprecation
===========
[](http://deprecation.readthedocs.io/en/latest/)
Fork of Brian Curtin's [deprecation](https://github.com/briancurtin/deprecation)
library, updated primarily for use in the
[`snakebids`](https://github.com/akhanf/snakebids) library.
The following README is copied from the original library, with relevant
modifications. The linked documentation is generally applicable, although
installation instructions will refer back to the original library.
# README
The `deprecated` library provides a `deprecated` decorator and a
`fail_if_not_removed` decorator for your tests. Together, the two enable the
automation of several things:
1. The docstring of a deprecated method gets the deprecation details appended to
the end of it. If you generate your API docs direct from your source, you
don't need to worry about writing your own notification. You also don't need
to worry about forgetting to write it. It's done for you.
2. Rather than having code live on forever because you only deprecated it but
never actually moved on from it, you can have your tests tell you when it's
time to remove the code. The `@deprecated` decorator can be told when it's
time to entirely remove the code, which causes `@fail_if_not_removed` to
raise an `AssertionError`, causing either your unittest or py.test tests to
fail.
See http://deprecation.readthedocs.io/ for the full documentation.
## Installation
```bash
pip install pvandyken.deprecated
```
## Usage
```py
from pvandyken import deprecated
@deprecated.deprecated(deprecated_in="1.0", removed_in="2.0",
current_version=__version__,
details="Use the bar function instead")
def foo():
"""Do some stuff"""
return 1
```
## ...but doesn't Python ignore `DeprecationWarning`?
Yes, by default since 2.7—and for good reason [^1] —and this works fine with
that.
1. It often makes sense for you to run your tests with a `-W` flag or the
`PYTHONWARNINGS` environment variable so you catch warnings in development
and handle them appropriately. The warnings raised by this library show up
there, as they're subclasses of the built-in `DeprecationWarning`. See the
[Command Line](https://docs.python.org/2/using/cmdline.html#cmdoption-W) and
[Environment
Variable](https://docs.python.org/2/using/cmdline.html#envvar-PYTHONWARNINGS)
documentation for more details.
2. Even if you don't enable those things, the behavior of this library remains
the same. The docstrings will still be updated and the tests will still fail
when they need to. You'll get the benefits regardless of what Python cares
about `DeprecationWarning`.
----
[^1]: Exposing application users to `DeprecationWarning`s that are emitted by
lower-level code needlessly involves end-users in "how things are done."
It often leads to users raising issues about warnings they're presented,
which on one hand is done rightfully so, as it's been presented to them as
some sort of issue to resolve. However, at the same time, the warning
could be well known and planned for. From either side, loud
`DeprecationWarning`s can be seen as noise that isn't necessary outside of
development.
Raw data
{
"_id": null,
"home_page": "",
"name": "pvandyken-deprecated",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Peter Van Dyken",
"author_email": "pvandyk2@uwo.ca",
"download_url": "https://files.pythonhosted.org/packages/d1/9e/18bf58a3535d79868e16b7f4dfd92d7df0368a9ae7405913d68b9856aba9/pvandyken_deprecated-0.0.4.tar.gz",
"platform": null,
"description": "deprecation\n===========\n\n[](http://deprecation.readthedocs.io/en/latest/)\n\nFork of Brian Curtin's [deprecation](https://github.com/briancurtin/deprecation)\nlibrary, updated primarily for use in the\n[`snakebids`](https://github.com/akhanf/snakebids) library.\n\n\nThe following README is copied from the original library, with relevant\nmodifications. The linked documentation is generally applicable, although\ninstallation instructions will refer back to the original library.\n\n\n# README\n\nThe `deprecated` library provides a `deprecated` decorator and a\n`fail_if_not_removed` decorator for your tests. Together, the two enable the\nautomation of several things:\n\n1. The docstring of a deprecated method gets the deprecation details appended to\n the end of it. If you generate your API docs direct from your source, you\n don't need to worry about writing your own notification. You also don't need\n to worry about forgetting to write it. It's done for you.\n2. Rather than having code live on forever because you only deprecated it but\n never actually moved on from it, you can have your tests tell you when it's\n time to remove the code. The `@deprecated` decorator can be told when it's\n time to entirely remove the code, which causes `@fail_if_not_removed` to\n raise an `AssertionError`, causing either your unittest or py.test tests to\n fail.\n\nSee http://deprecation.readthedocs.io/ for the full documentation.\n\n## Installation\n\n```bash\npip install pvandyken.deprecated\n```\n\n## Usage\n\n```py\n\nfrom pvandyken import deprecated\n\n@deprecated.deprecated(deprecated_in=\"1.0\", removed_in=\"2.0\",\n current_version=__version__,\n details=\"Use the bar function instead\")\ndef foo():\n \"\"\"Do some stuff\"\"\"\n return 1\n```\n\n## ...but doesn't Python ignore `DeprecationWarning`?\n\nYes, by default since 2.7\u2014and for good reason [^1] \u2014and this works fine with\nthat.\n\n1. It often makes sense for you to run your tests with a `-W` flag or the\n `PYTHONWARNINGS` environment variable so you catch warnings in development\n and handle them appropriately. The warnings raised by this library show up\n there, as they're subclasses of the built-in `DeprecationWarning`. See the\n [Command Line](https://docs.python.org/2/using/cmdline.html#cmdoption-W) and\n [Environment\n Variable](https://docs.python.org/2/using/cmdline.html#envvar-PYTHONWARNINGS)\n documentation for more details.\n2. Even if you don't enable those things, the behavior of this library remains\n the same. The docstrings will still be updated and the tests will still fail\n when they need to. You'll get the benefits regardless of what Python cares\n about `DeprecationWarning`.\n\n----\n\n[^1]: Exposing application users to `DeprecationWarning`s that are emitted by\n lower-level code needlessly involves end-users in \"how things are done.\"\n It often leads to users raising issues about warnings they're presented,\n which on one hand is done rightfully so, as it's been presented to them as\n some sort of issue to resolve. However, at the same time, the warning\n could be well known and planned for. From either side, loud\n `DeprecationWarning`s can be seen as noise that isn't necessary outside of\n development.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Wrapper to manage deprecations",
"version": "0.0.4",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a61a32704fc4d278af117f8c8a3cbc59d5f0764a94b560c66be43d2bd1dcdc8",
"md5": "47fe3950ac3a669ef4fff490d8ef1898",
"sha256": "6e58ea8ef598211f539c3eab415bf39001b4276999e19a4354ffa82be83990a0"
},
"downloads": -1,
"filename": "pvandyken_deprecated-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47fe3950ac3a669ef4fff490d8ef1898",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11732,
"upload_time": "2023-09-20T20:41:29",
"upload_time_iso_8601": "2023-09-20T20:41:29.407162Z",
"url": "https://files.pythonhosted.org/packages/1a/61/a32704fc4d278af117f8c8a3cbc59d5f0764a94b560c66be43d2bd1dcdc8/pvandyken_deprecated-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d19e18bf58a3535d79868e16b7f4dfd92d7df0368a9ae7405913d68b9856aba9",
"md5": "e55c87c6ce3b6c550f37e31ae05476f1",
"sha256": "ea174be2fd36495fef0e4818c080eccbc6ec9a8ddc177cb9d859cd0044b1b5b0"
},
"downloads": -1,
"filename": "pvandyken_deprecated-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "e55c87c6ce3b6c550f37e31ae05476f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10835,
"upload_time": "2023-09-20T20:41:30",
"upload_time_iso_8601": "2023-09-20T20:41:30.892421Z",
"url": "https://files.pythonhosted.org/packages/d1/9e/18bf58a3535d79868e16b7f4dfd92d7df0368a9ae7405913d68b9856aba9/pvandyken_deprecated-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-20 20:41:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pvandyken-deprecated"
}
