| Name | zeugvars JSON |
| Version |
0.2.7
JSON |
| download |
| home_page | https://github.com/bswck/zeugvars |
| Summary | A simple & straight-forward Python module for creating context-dependent proxy objects. |
| upload_time | 2023-07-13 23:32:13 |
| maintainer | |
| docs_url | None |
| author | bswck |
| requires_python | >=3.10,<4.0 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## `zeugvars`
A simple & straight-forward Python library for creating type-safe, context-dependent proxy objects.
## Example
The following example shows how to use `zeugvars` with `contextvars`:
```python
>>> from contextvars import ContextVar
>>> from zeugvars import proxy
...
>>> count_var = ContextVar("count_var")
>>> count = proxy(counter, 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?
`zeugvars` 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 `zeugvars.zeugvar()` (or, as you prefer, `zeugvars.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 `Manage.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 `zeugvars`?
You could use `zeugvars` when...
* ...writing a thread-safe application that operates on fixed 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 fixed resources per request.
* ...writing an asynchronous application that operates on fixed resources between tasks.
* ...having any other case where you could use global variables that are context-dependent!
## Why does it have such a weird name?
The name is a reference to the pallets' `werkzeug` library, which is a German word for 'tool'.
'zeug' is a German word for 'stuff' or 'things'. 'vars' is an abbreviation for 'variables'.
I think now you can see where the name comes from.
## Installation
### pip
```bash
$ pip install zeugvars
```
### poetry
You can add `zeugvars` as a dependency with the following command:
```bash
$ poetry add zeugvars
```
Or by directly specifying it in the configuration like so:
```toml
[tool.poetry.dependencies]
"zeugvars" = "^0.2.0"
```
Alternatively, you can add it directly from the source:
```toml
[tool.poetry.dependencies.zeugvars]
git = "https://github.com/bswck/zeugvars.git"
```
## Documentation
### `zeugvars.zeugvar(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/zeugvars",
"name": "zeugvars",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "bswck",
"author_email": "bswck.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/49/a3f10df788b32cbb3a14963a67ac23a3f45a8a8eb036021ced1dc3425814/zeugvars-0.2.7.tar.gz",
"platform": null,
"description": "## `zeugvars`\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 `zeugvars` with `contextvars`:\n\n```python\n>>> from contextvars import ContextVar\n>>> from zeugvars import proxy\n...\n>>> count_var = ContextVar(\"count_var\")\n>>> count = proxy(counter, 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`zeugvars` 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 `zeugvars.zeugvar()` (or, as you prefer, `zeugvars.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 `Manage.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 `zeugvars`?\n\nYou could use `zeugvars` when...\n* ...writing a thread-safe application that operates on fixed 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 fixed resources per request.\n* ...writing an asynchronous application that operates on fixed resources between tasks.\n* ...having any other case where you could use global variables that are context-dependent!\n\n## Why does it have such a weird name?\n\nThe name is a reference to the pallets' `werkzeug` library, which is a German word for 'tool'.\n'zeug' is a German word for 'stuff' or 'things'. 'vars' is an abbreviation for 'variables'.\nI think now you can see where the name comes from.\n\n## Installation\n\n### pip\n```bash\n$ pip install zeugvars\n```\n\n### poetry\n\nYou can add `zeugvars` as a dependency with the following command:\n\n```bash\n$ poetry add zeugvars\n```\n\nOr by directly specifying it in the configuration like so:\n\n```toml\n[tool.poetry.dependencies]\n\"zeugvars\" = \"^0.2.0\"\n```\n\nAlternatively, you can add it directly from the source:\n\n```toml\n[tool.poetry.dependencies.zeugvars]\ngit = \"https://github.com/bswck/zeugvars.git\"\n```\n\n## Documentation\n\n### `zeugvars.zeugvar(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",
"bugtrack_url": null,
"license": "",
"summary": "A simple & straight-forward Python module for creating context-dependent proxy objects.",
"version": "0.2.7",
"project_urls": {
"Homepage": "https://github.com/bswck/zeugvars"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b9717275ef31ca0ed2c8f26ec8c89bb69555d5306f95b76d7cbc73ebae32c9cb",
"md5": "ece67afac932bd87a0a46d838d4ed4c4",
"sha256": "40fd3a1d912d12dda83db308bac8b53b736fca598d9752ca7a1b3a051d7503c4"
},
"downloads": -1,
"filename": "zeugvars-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ece67afac932bd87a0a46d838d4ed4c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 5767,
"upload_time": "2023-07-13T23:32:12",
"upload_time_iso_8601": "2023-07-13T23:32:12.092702Z",
"url": "https://files.pythonhosted.org/packages/b9/71/7275ef31ca0ed2c8f26ec8c89bb69555d5306f95b76d7cbc73ebae32c9cb/zeugvars-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c49a3f10df788b32cbb3a14963a67ac23a3f45a8a8eb036021ced1dc3425814",
"md5": "97a94cf552b09f0d66e51f46429da9de",
"sha256": "3a84c13d426f8612771739bbd897d20bcfc2c560ba52c28b1d33b7b1370dfb6f"
},
"downloads": -1,
"filename": "zeugvars-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "97a94cf552b09f0d66e51f46429da9de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 6317,
"upload_time": "2023-07-13T23:32:13",
"upload_time_iso_8601": "2023-07-13T23:32:13.941730Z",
"url": "https://files.pythonhosted.org/packages/1c/49/a3f10df788b32cbb3a14963a67ac23a3f45a8a8eb036021ced1dc3425814/zeugvars-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-13 23:32:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bswck",
"github_project": "zeugvars",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zeugvars"
}
