| Name | commonvars JSON |
| Version |
0.4.2
JSON |
| download |
| home_page | https://github.com/bswck/commonvars |
| Summary | A simple & straight-forward Python module for creating context-dependent proxy objects. |
| upload_time | 2023-08-23 19:21:10 |
| maintainer | |
| docs_url | None |
| author | bswck |
| requires_python | >=3.8,<4.0 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## commonvars `v0.4.2`
A simple & straight-forward Python library for creating type-safe, context-dependent proxy objects.
## Example
The following example shows how to use `commonvars` with `contextvars`:
```python
>>> from contextvars import ContextVar
>>> from commonvars import commonvar
...
>>> count_var = ContextVar("count_var")
>>> count = commonvar(count_var, int)
...
>>> count
<unbound 'int' object>
>>> count_var.set(0)
>>> count
0
>>> count += 1
>>> count
1
>>> count_var.get()
1
>>> count -= 1
>>> count
0
>>> count_var.set(1000)
<Token var=<ContextVar name='count_var' at ...> at ...>
>>> count
1000
```
## Ok, but what is this?
`commonvars` is a Python module for creating context-dependent proxy objects.
By 'proxy' we mean any object that forwards attribute access to another
object. By 'context-dependent' we mean that the object to which the proxy
forwards attribute access can change depending on the context in which the
proxy is used.
### Have you ever wondered how `flask.request` works?
How is it possible
that [`flask.request`](https://tedboy.github.io/flask/interface_api.incoming_request_data.html?highlight=request#flask.request)
is different for each request, despite being a global variable?
The answer is that `flask.request` is a such a proxy object as an instance of `werkzeug.local.LocalProxy`.
For every request, `flask.request` forwards attribute access to a different `flask.Request` object.
The functionality of `commonvars.commonvar()` (or, as you prefer, `commonvars.proxy()`) is a more generic version of `werkzeug.local.LocalProxy`.
It takes a `Manager` object and the class of the object to which the proxy points.
The `Manager` object must have `get` and `set` methods. The `get` method returns
the object to which the would forward attribute access. The `set` method sets it, obviously.
`set` is called when the proxy is being inplace modified, for example within the `+=` reassigning operator.
The class parameter is optional, but it is strongly recommended for some corner-cases.
The user might provide custom `getter` and `setter` functions that change the way
`Manager.get()` and `Manager.set()` are called.
This might be useful when there is the need to keep track of the tokens
returned by `ContextVar.set()`, if using `ContextVar` as the manager.
## When would you use `commonvars`?
You could use `commonvars` when...
* ...writing a thread-safe application that operates on resources specific for separate threads.
* ...improving code readability by avoiding passing around the same object to every function.
* ...writing a web application that operates on resources specific per request.
* ...writing an asynchronous application that operates on resources specific between tasks.
* ...having any other case where you could use common variables that are context-dependent!
## Installation
### pip
```bash
$ pip install commonvars
```
### [poetry](https://python-poetry.org/)
You can add `commonvars` as a dependency with the following command:
```bash
$ poetry add commonvars
```
Or by directly specifying it in the configuration like so:
```toml
[tool.poetry.dependencies]
"commonvars" = "^0.4.2"
```
Alternatively, you can add it directly from the source:
```toml
[tool.poetry.dependencies.commonvars]
git = "https://github.com/bswck/commonvars.git"
```
## Documentation
### `commonvars.commonvar(mgr, cls=None, getter=None, setter=None)`
Creates a context-dependent proxy object.
#### Parameters
* `manager`: Manager object. Must implement the `Manager` protocol. Matches `contextvars.ContextVar`.
* `cls`: The class of the underlying variable accessed within the manager. Optional.
* `getter`: A function that returns the underlying variable from the manager. Optional.
* `setter`: A function that sets the underlying variable within the manager. Optional.
Raw data
{
"_id": null,
"home_page": "https://github.com/bswck/commonvars",
"name": "commonvars",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "bswck",
"author_email": "bswck.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/61/ff/414913a1ef678db52d99daf3eced4bef9b5ba7959c77be7098fc0bde0bf1/commonvars-0.4.2.tar.gz",
"platform": null,
"description": "## commonvars `v0.4.2`\n\nA simple & straight-forward Python library for creating type-safe, context-dependent proxy objects.\n\n## Example\n\nThe following example shows how to use `commonvars` with `contextvars`:\n\n```python\n>>> from contextvars import ContextVar\n>>> from commonvars import commonvar\n...\n>>> count_var = ContextVar(\"count_var\")\n>>> count = commonvar(count_var, int)\n...\n>>> count\n<unbound 'int' object>\n>>> count_var.set(0)\n>>> count\n0\n>>> count += 1\n>>> count\n1\n>>> count_var.get()\n1\n>>> count -= 1\n>>> count\n0\n>>> count_var.set(1000)\n<Token var=<ContextVar name='count_var' at ...> at ...>\n>>> count\n1000\n```\n\n## Ok, but what is this?\n\n`commonvars` is a Python module for creating context-dependent proxy objects.\n\nBy 'proxy' we mean any object that forwards attribute access to another\nobject. By 'context-dependent' we mean that the object to which the proxy\nforwards attribute access can change depending on the context in which the\nproxy is used.\n\n### Have you ever wondered how `flask.request` works?\n\nHow is it possible\nthat [`flask.request`](https://tedboy.github.io/flask/interface_api.incoming_request_data.html?highlight=request#flask.request)\nis different for each request, despite being a global variable?\n\nThe answer is that `flask.request` is a such a proxy object as an instance of `werkzeug.local.LocalProxy`.\nFor every request, `flask.request` forwards attribute access to a different `flask.Request` object.\n\nThe functionality of `commonvars.commonvar()` (or, as you prefer, `commonvars.proxy()`) is a more generic version of `werkzeug.local.LocalProxy`.\n\nIt takes a `Manager` object and the class of the object to which the proxy points.\n\nThe `Manager` object must have `get` and `set` methods. The `get` method returns\nthe object to which the would forward attribute access. The `set` method sets it, obviously.\n`set` is called when the proxy is being inplace modified, for example within the `+=` reassigning operator.\nThe class parameter is optional, but it is strongly recommended for some corner-cases.\nThe user might provide custom `getter` and `setter` functions that change the way\n`Manager.get()` and `Manager.set()` are called.\nThis might be useful when there is the need to keep track of the tokens\nreturned by `ContextVar.set()`, if using `ContextVar` as the manager.\n\n## When would you use `commonvars`?\n\nYou could use `commonvars` when...\n* ...writing a thread-safe application that operates on resources specific for separate threads.\n* ...improving code readability by avoiding passing around the same object to every function.\n* ...writing a web application that operates on resources specific per request.\n* ...writing an asynchronous application that operates on resources specific between tasks.\n* ...having any other case where you could use common variables that are context-dependent!\n\n## Installation\n\n### pip\n```bash\n$ pip install commonvars\n```\n\n### [poetry](https://python-poetry.org/)\n\nYou can add `commonvars` as a dependency with the following command:\n\n```bash\n$ poetry add commonvars\n```\n\nOr by directly specifying it in the configuration like so:\n\n```toml\n[tool.poetry.dependencies]\n\"commonvars\" = \"^0.4.2\"\n```\n\nAlternatively, you can add it directly from the source:\n\n```toml\n[tool.poetry.dependencies.commonvars]\ngit = \"https://github.com/bswck/commonvars.git\"\n```\n\n## Documentation\n\n### `commonvars.commonvar(mgr, cls=None, getter=None, setter=None)`\n\nCreates a context-dependent proxy object.\n\n#### Parameters\n* `manager`: Manager object. Must implement the `Manager` protocol. Matches `contextvars.ContextVar`.\n* `cls`: The class of the underlying variable accessed within the manager. Optional.\n* `getter`: A function that returns the underlying variable from the manager. Optional.\n* `setter`: A function that sets the underlying variable within the manager. Optional.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A simple & straight-forward Python module for creating context-dependent proxy objects.",
"version": "0.4.2",
"project_urls": {
"Homepage": "https://github.com/bswck/commonvars"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b95daa9177218ae4199a8c458ee846a813e27ba77eb2fe3a830329a692c300c",
"md5": "460260791912b8ae7babccc3f16139ee",
"sha256": "04b38b6de0a6bbc17dacbc40e480235c98b7a7feab3055d5847dc8550e664bd1"
},
"downloads": -1,
"filename": "commonvars-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "460260791912b8ae7babccc3f16139ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 6089,
"upload_time": "2023-08-23T19:21:08",
"upload_time_iso_8601": "2023-08-23T19:21:08.977948Z",
"url": "https://files.pythonhosted.org/packages/8b/95/daa9177218ae4199a8c458ee846a813e27ba77eb2fe3a830329a692c300c/commonvars-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61ff414913a1ef678db52d99daf3eced4bef9b5ba7959c77be7098fc0bde0bf1",
"md5": "c6528137a4d157a1ed87b5b86bbae235",
"sha256": "ba2ef14d9d800cbaf0328bcf50bc53014a1011c7055de5c841c4c81917188538"
},
"downloads": -1,
"filename": "commonvars-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "c6528137a4d157a1ed87b5b86bbae235",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 6249,
"upload_time": "2023-08-23T19:21:10",
"upload_time_iso_8601": "2023-08-23T19:21:10.353411Z",
"url": "https://files.pythonhosted.org/packages/61/ff/414913a1ef678db52d99daf3eced4bef9b5ba7959c77be7098fc0bde0bf1/commonvars-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-23 19:21:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bswck",
"github_project": "commonvars",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "commonvars"
}
