| Name | housekeeping JSON |
| Version |
1.1
JSON |
| download |
| home_page | |
| Summary | Python utilities for helping deprecate and remove code. |
| upload_time | 2023-06-23 23:21:00 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
deprecation
cleanup
code quality
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Housekeeping for Python
Housekeeping is a Python package designed to make it easy for projects to mark
consumed code as deprecated or pending deprecation, with helpful instructions
for consumers using deprecated functionality.
It's built with the lessons we learned in
[Review Board](https://www.reviewboard.org),
[Djblets](https://github.com/djblets/djblets), and
[RBTools](https://www.reviewboard.org/downloads/rbtools/).
With Housekeeping, you can easily manage deprecations in your code, helping you
and any consumers of your code transition to the latest and greatest.
It offers decorators, mixins, and functions to help with deprecating functions,
methods, classes, modules, attributes, parameters, and dictionary keys.
Housekeeping is licensed under the MIT license.
## Installing Housekeeping
Housekeeping is built as a utility library for your project. It should be
added to your project's list of dependencies.
To install it manually, run:
```console
$ pip install housekeeping
```
Housekeeping follows [semantic versioning](https://semver.org/), meaning no
surprises when you upgrade.
## Using Housekeeping In Your Project
### Add Your Deprecation Classes
Add base deprecation warning classes to your project.
There are two categories of warnings:
* **Deprecation warnings**, which mark code as being deprecated and
scheduled for removal in a specific upcoming version.
* **Pending deprecation warnings**, which mark code as being available but
scheduled to be deprecated in an unknown future version. Projects should
later transition these to full deprecation warnings.
You'll be creating classes for each type that identify your project and any
upcoming versions where deprecated code may be removed.
We recommend adding these to the ``<project_name>.deprecation`` module.
For example:
```python
from housekeeping import BasePendingRemovalWarning, BaseRemovedInWarning
class PendingRemovalInMyProjectWarning(BasePendingRemovalWarning):
project = 'My Project'
class BaseRemovedInMyProjectWarning(BaseRemovedInWarning):
project = 'My Project'
class RemovedInMyProject20Warning(BaseRemovedInMyProjectWarning):
version = '2.0'
class RemovedInMyProject30Warning(BaseRemovedInMyProjectWarning):
version = '3.0'
...
```
### Begin Deprecating Code
Housekeeping offers several deprecation helpers to deprecate code.
You can also call `.warn()` on your deprecation classes to warn about
deprecated code at any time.
#### Deprecating Functions
##### `@deprecate_non_keyword_only_args`
This decorator can help convert positional arguments to keyword-only arguments:
```python
from housekeeping import deprecate_non_keyword_only_args
@deprecate_non_keyword_only_args(RemovedInMyProject20Warning)
def add_abc(a, *, b, c=1):
return a + b + c
add_abc(1, 2, 3) # This will emit a deprecation warning.
add_abc(1, b=2, c=3) # This will not.
````
##### `@func_deprecated`
This decorator marks a function as deprecated, or pending deprecation:
```python
from housekeeping import func_deprecated
@func_deprecated(RemovedInMyProject20Warning)
def my_func():
...
my_func() # This will emit a deprecation warning.
```
##### `@func_moved`
This decorator marks a function as having moved elsewhere.
```python
from housekeeping import func_moved
from myproject.new_module import my_func as new_my_func
# This can be invoked with some special behavior:
@func_moved(RemovedInMyProject20Warning,
new_func=new_my_func)
def my_func(a, b):
new_my_func(a, b, True)
my_func() # This will emit a deprecation warning.
```
##### `deprecated_arg_value`
This wraps values that, when accessed, emit a deprecation or pending
deprecation warning. It's useful for passing legacy data to callback handlers.
```python
from housekeeping import deprecated_arg_value
def callback_handler(username=None, user=None):
user = get_user(username) # This will emit a deprecation warning.
user = get_user(user) # This would not.
class User:
...
def emit_did_thing(self):
callback_handler(
user=self,
username=deprecated_arg_value(
RemovedInMyProject20Warning,
owner_name='User',
value=self.username,
old_name='username',
new_name='user'))
```
#### Deprecating Classes
#### `ClassDeprecatedMixin`
This class mixin will emit warnings when you either instantiate or subclass
the class.
```python
from housekeeping import ClassDeprecatedMixin
class MyOldClass(ClassDeprecatedMixin,
warning_cls=RemovedInMyProject20Warning):
pass
# This will emit a deprecation warning.
MyOldClass()
# So will this.
class MyChildClass(OldBaseClass):
pass
# But this will not.
MyChildClass()
# Nor will this.
class MyGrandChildClass(MyChildClass):
pass
```
#### `ClassMovedMixin`
This class mixin will emit warnings when you either instantiate or subclass
the class, pointing you to a replacement class or import.
```python
from housekeeping import ClassDeprecatedMixin
class MyOldClass(ClassMovedMixin, MyNewBaseClass,
warning_cls=RemovedInMyProject20Warning):
pass
# This will emit a deprecation warning.
MyOldClass()
# So will this.
class MyChildClass(MyOldClass):
pass
# But this will not.
MyChildClass()
# Nor will this.
class MyGrandChildClass(MyChildClass):
pass
```
#### Deprecating Modules
##### ``module_deprecated``
This function can be called within a module body to emit a warning when the
module is imported.
```python
from housekeeping import module_deprecated
from myproject.deprecation import RemovedInMyProject20Warning
module_deprecated(RemovedInMyProject20Warning, __name__)
```
##### ``module_moved``
This function can be called within a module body to emit a warning when the
module is imported, pointing the consumer to a replacement module. This is
useful when reorganizing the codebase and moving modules around.
```python
from housekeeping import module_moved
from myproject.deprecation import RemovedInMyProject20Warning
from myproject import newmodule
module_moved(RemovedInMyProject20Warning, __name__, newmodule.__name__)
```
Our Other Projects
------------------
* [Review Board](https://www.reviewboard.org) -
Our free, open source, extensible code and document review tool.
* [Djblets](https://github.com/djblets/djblets/) -
Our pack of Django utilities for datagrids, API, extensions, and more. Used
by Review Board.
* [Review Bot](https://www.reviewboard.org/downloads/reviewbot/) -
Automated code review for Review Board.
You can see more on [github.com/beanbaginc](https://github.com/beanbaginc) and
[github.com/reviewboard](https://github.com/reviewboard).
Raw data
{
"_id": null,
"home_page": "",
"name": "housekeeping",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "deprecation,cleanup,code quality",
"author": "",
"author_email": "\"Beanbag, Inc.\" <questions@beanbaginc.com>",
"download_url": "https://files.pythonhosted.org/packages/a7/56/2e66e26b44f3970d9d6aed1ab1b5dce8a741bc7f0c2918f222831e130c5a/housekeeping-1.1.tar.gz",
"platform": null,
"description": "# Housekeeping for Python\n\nHousekeeping is a Python package designed to make it easy for projects to mark\nconsumed code as deprecated or pending deprecation, with helpful instructions\nfor consumers using deprecated functionality.\n\nIt's built with the lessons we learned in\n[Review Board](https://www.reviewboard.org),\n[Djblets](https://github.com/djblets/djblets), and\n[RBTools](https://www.reviewboard.org/downloads/rbtools/).\n\nWith Housekeeping, you can easily manage deprecations in your code, helping you\nand any consumers of your code transition to the latest and greatest.\n\nIt offers decorators, mixins, and functions to help with deprecating functions,\nmethods, classes, modules, attributes, parameters, and dictionary keys.\n\nHousekeeping is licensed under the MIT license.\n\n\n## Installing Housekeeping\n\nHousekeeping is built as a utility library for your project. It should be\nadded to your project's list of dependencies.\n\nTo install it manually, run:\n\n```console\n$ pip install housekeeping\n```\n\nHousekeeping follows [semantic versioning](https://semver.org/), meaning no\nsurprises when you upgrade.\n\n\n## Using Housekeeping In Your Project\n\n### Add Your Deprecation Classes\n\nAdd base deprecation warning classes to your project.\n\nThere are two categories of warnings:\n\n* **Deprecation warnings**, which mark code as being deprecated and\n scheduled for removal in a specific upcoming version.\n\n* **Pending deprecation warnings**, which mark code as being available but\n scheduled to be deprecated in an unknown future version. Projects should\n later transition these to full deprecation warnings.\n\nYou'll be creating classes for each type that identify your project and any\nupcoming versions where deprecated code may be removed.\n\nWe recommend adding these to the ``<project_name>.deprecation`` module.\n\nFor example:\n\n```python\nfrom housekeeping import BasePendingRemovalWarning, BaseRemovedInWarning\n\n\nclass PendingRemovalInMyProjectWarning(BasePendingRemovalWarning):\n project = 'My Project'\n\n\nclass BaseRemovedInMyProjectWarning(BaseRemovedInWarning):\n project = 'My Project'\n\n\nclass RemovedInMyProject20Warning(BaseRemovedInMyProjectWarning):\n version = '2.0'\n\n\nclass RemovedInMyProject30Warning(BaseRemovedInMyProjectWarning):\n version = '3.0'\n\n...\n```\n\n\n### Begin Deprecating Code\n\nHousekeeping offers several deprecation helpers to deprecate code.\n\nYou can also call `.warn()` on your deprecation classes to warn about\ndeprecated code at any time.\n\n\n#### Deprecating Functions\n\n##### `@deprecate_non_keyword_only_args`\n\nThis decorator can help convert positional arguments to keyword-only arguments:\n\n```python\nfrom housekeeping import deprecate_non_keyword_only_args\n\n\n@deprecate_non_keyword_only_args(RemovedInMyProject20Warning)\ndef add_abc(a, *, b, c=1):\n return a + b + c\n\n\nadd_abc(1, 2, 3) # This will emit a deprecation warning.\nadd_abc(1, b=2, c=3) # This will not.\n````\n\n\n##### `@func_deprecated`\n\nThis decorator marks a function as deprecated, or pending deprecation:\n\n```python\nfrom housekeeping import func_deprecated\n\n\n@func_deprecated(RemovedInMyProject20Warning)\ndef my_func():\n ...\n\n\nmy_func() # This will emit a deprecation warning.\n```\n\n\n##### `@func_moved`\n\nThis decorator marks a function as having moved elsewhere.\n\n```python\nfrom housekeeping import func_moved\n\nfrom myproject.new_module import my_func as new_my_func\n\n\n# This can be invoked with some special behavior:\n@func_moved(RemovedInMyProject20Warning,\n new_func=new_my_func)\ndef my_func(a, b):\n new_my_func(a, b, True)\n\n\nmy_func() # This will emit a deprecation warning.\n```\n\n\n##### `deprecated_arg_value`\n\nThis wraps values that, when accessed, emit a deprecation or pending\ndeprecation warning. It's useful for passing legacy data to callback handlers.\n\n```python\nfrom housekeeping import deprecated_arg_value\n\n\ndef callback_handler(username=None, user=None):\n user = get_user(username) # This will emit a deprecation warning.\n user = get_user(user) # This would not.\n\n\nclass User:\n ...\n\n def emit_did_thing(self):\n callback_handler(\n user=self,\n username=deprecated_arg_value(\n RemovedInMyProject20Warning,\n owner_name='User',\n value=self.username,\n old_name='username',\n new_name='user'))\n```\n\n#### Deprecating Classes\n\n#### `ClassDeprecatedMixin`\n\nThis class mixin will emit warnings when you either instantiate or subclass\nthe class.\n\n```python\nfrom housekeeping import ClassDeprecatedMixin\n\n\nclass MyOldClass(ClassDeprecatedMixin,\n warning_cls=RemovedInMyProject20Warning):\n pass\n\n# This will emit a deprecation warning.\nMyOldClass()\n\n# So will this.\nclass MyChildClass(OldBaseClass):\n pass\n\n# But this will not.\nMyChildClass()\n\n# Nor will this.\nclass MyGrandChildClass(MyChildClass):\n pass\n```\n\n\n#### `ClassMovedMixin`\n\nThis class mixin will emit warnings when you either instantiate or subclass\nthe class, pointing you to a replacement class or import.\n\n```python\nfrom housekeeping import ClassDeprecatedMixin\n\n\nclass MyOldClass(ClassMovedMixin, MyNewBaseClass,\n warning_cls=RemovedInMyProject20Warning):\n pass\n\n# This will emit a deprecation warning.\nMyOldClass()\n\n# So will this.\nclass MyChildClass(MyOldClass):\n pass\n\n# But this will not.\nMyChildClass()\n\n# Nor will this.\nclass MyGrandChildClass(MyChildClass):\n pass\n```\n\n\n#### Deprecating Modules\n\n##### ``module_deprecated``\n\nThis function can be called within a module body to emit a warning when the\nmodule is imported.\n\n```python\nfrom housekeeping import module_deprecated\n\nfrom myproject.deprecation import RemovedInMyProject20Warning\n\n\nmodule_deprecated(RemovedInMyProject20Warning, __name__)\n```\n\n\n##### ``module_moved``\n\nThis function can be called within a module body to emit a warning when the\nmodule is imported, pointing the consumer to a replacement module. This is\nuseful when reorganizing the codebase and moving modules around.\n\n```python\nfrom housekeeping import module_moved\n\nfrom myproject.deprecation import RemovedInMyProject20Warning\nfrom myproject import newmodule\n\n\nmodule_moved(RemovedInMyProject20Warning, __name__, newmodule.__name__)\n```\n\n\nOur Other Projects\n------------------\n\n* [Review Board](https://www.reviewboard.org) -\n Our free, open source, extensible code and document review tool.\n* [Djblets](https://github.com/djblets/djblets/) -\n Our pack of Django utilities for datagrids, API, extensions, and more. Used\n by Review Board.\n* [Review Bot](https://www.reviewboard.org/downloads/reviewbot/) -\n Automated code review for Review Board.\n\nYou can see more on [github.com/beanbaginc](https://github.com/beanbaginc) and\n[github.com/reviewboard](https://github.com/reviewboard).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python utilities for helping deprecate and remove code.",
"version": "1.1",
"project_urls": {
"documentation": "https://github.com/beanbaginc/housekeeping",
"homepage": "https://github.com/beanbaginc/housekeeping",
"repository": "https://github.com/beanbaginc/housekeeping"
},
"split_keywords": [
"deprecation",
"cleanup",
"code quality"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62e2a1ef21c010b6220b37540adbc57ce20aeb07f19c5926bbcbbac5921ac985",
"md5": "16e648e81af95f57f92ed4b53a357122",
"sha256": "631a1ff99a34ac84f49ce14ff8e01900b3911101de99660ccb00d6529184eb8c"
},
"downloads": -1,
"filename": "housekeeping-1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16e648e81af95f57f92ed4b53a357122",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21968,
"upload_time": "2023-06-23T23:20:58",
"upload_time_iso_8601": "2023-06-23T23:20:58.802518Z",
"url": "https://files.pythonhosted.org/packages/62/e2/a1ef21c010b6220b37540adbc57ce20aeb07f19c5926bbcbbac5921ac985/housekeeping-1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a7562e66e26b44f3970d9d6aed1ab1b5dce8a741bc7f0c2918f222831e130c5a",
"md5": "83cc38eeddb1e9b453885c517c7e58fa",
"sha256": "75e71f1cc501885406f6be81410c9b05361871a3ecccde3891336da1e92426b5"
},
"downloads": -1,
"filename": "housekeeping-1.1.tar.gz",
"has_sig": false,
"md5_digest": "83cc38eeddb1e9b453885c517c7e58fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19346,
"upload_time": "2023-06-23T23:21:00",
"upload_time_iso_8601": "2023-06-23T23:21:00.538714Z",
"url": "https://files.pythonhosted.org/packages/a7/56/2e66e26b44f3970d9d6aed1ab1b5dce8a741bc7f0c2918f222831e130c5a/housekeeping-1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-23 23:21:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "beanbaginc",
"github_project": "housekeeping",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "housekeeping"
}
