| Name | jafdecs JSON |
| Version |
0.1.0a2
JSON |
| download |
| home_page | |
| Summary | A few useful decorators for Python functions, classes, class methods, and properties. |
| upload_time | 2023-07-02 15:55:31 |
| maintainer | |
| docs_url | None |
| author | Doug McGeehan |
| requires_python | >=3.7 |
| license | GPLv3 |
| keywords |
decorators
caching
write once read many
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
================================
`jafdecs`: Just A Few Decorators
================================
Pretty useful decorators for Python functions, classes, and class methods.
Write Once, Read Many on Class Properties
=========================================
If a class property takes a long time to compute and is referenced many times, it is useful to lazily compute it once (when it is first referenced) and cache the result for later references.
This is where the ``worm`` submodule comes in.
::
class SlowExample:
@property
def hard_property(self):
import time
time.sleep(5)
print('This took a long time to compute!')
return 5
ex = SlowExample()
print(ex.hard_property)
print(ex.hard_property)
In the example above, the code will take around 10 seconds to run.
But it only needs to take 5 seconds if the property's value is cached, like in the example below.
::
from jafdecs import worm
@worm.onproperties
class QuickerExample:
@property
def hard_property(self):
import time
time.sleep(5)
print('This took a long time to compute!')
return 5
ex = QuickerExample()
print(ex.hard_property)
print(ex.hard_property)
Prime a function by executing something before
==============================================
Consider a function that takes a long time to compute a value, but once it is computed it may be used over and over again.
Exploiting this reusability is the idea behind memoization.
The Python standard library offers the ``functools.cache()`` and ``functools.lru_cache()`` decorators.
However, two limitations come to mind in use cases where memoization applies:
* The returned value is very big and cannot feasibly be cached in memory
* Programmatic control over when to pull from cache or recompute is not available
For either situation, the ``jafdecs.initialize.by(...)`` decorator can help.
Consider the examples below.
::
def naive_function(path: pathlib.Path):
# This code is somewhat complicated in that it initializes an asset before using it, unless the asset already exists.
if not path.exists():
print(f'File at {path} does not exist, so we will generate it before calling the actual function that needs it')
generated_value = {}
n = 18
for i in range(10):
key = str(i)
value = i
generated_value[key] = value
print('Sleeping to simulate a hard-to-compute function.')
time.sleep(2)
with path.open('w') as file:
json.dump(generated_value, file)
print(f'File at {path} now exists, so we can get its data.')
with path.open() as file:
value = json.load(file)
pprint(value)
naive_function(path=pathlib.Path('example.json'))
In the example above, the code initializes an asset if it doesn't exist, and then uses that asset when it does.
If the asset already existed, it skips the initialization entirely.
For the sake of code cleanliness and ease of reading, the ``jafdecs.initialize.by(...)`` decorator allows these two distinct code blocks to be separated.
::
from jafdecs import initialize, utilities
import pathlib
import time
import json
from pprint import pprint
def priming_function(path: pathlib.Path):
print(f'File at {path} does not exist, so we will generate it before calling the actual function that needs it')
generated_value = {}
for i in range(10):
key = str(i)
value = i
generated_value[key] = value
print('Sleeping to simulate a hard-to-compute function.')
time.sleep(2)
with path.open('w') as file:
json.dump(generated_value, file)
@initialize.by(func=priming_function, condition=utilities.filenotfound)
def actual_function(path: pathlib.Path):
print(f'File at {path} now exists, so we can get its data.')
with path.open() as file:
value = json.load(file)
pprint(value)
actual_function(path=pathlib.Path('example.json'))
actual_function(path=pathlib.Path('example.json'))
In the example above, the initializing code is separated in its own function, reducing the clutter in the actual function to only the code that is needed to speed things up.
The first execution is primed by the initializing function.
When the second execution is called, no priming is needed.
The assets produced by the first priming are reused.
Raw data
{
"_id": null,
"home_page": "",
"name": "jafdecs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "decorators,caching,write once read many",
"author": "Doug McGeehan",
"author_email": "doug@kmnr.org",
"download_url": "https://files.pythonhosted.org/packages/7c/6f/368ffedc93cacffe4a611f8bc283503fe123273a22400c858d5ca9f4e9d6/jafdecs-0.1.0a2.tar.gz",
"platform": null,
"description": "================================\n`jafdecs`: Just A Few Decorators\n================================\n\nPretty useful decorators for Python functions, classes, and class methods.\n\n\nWrite Once, Read Many on Class Properties\n=========================================\n\nIf a class property takes a long time to compute and is referenced many times, it is useful to lazily compute it once (when it is first referenced) and cache the result for later references.\nThis is where the ``worm`` submodule comes in.\n\n::\n\n class SlowExample:\n @property\n def hard_property(self):\n import time\n time.sleep(5)\n print('This took a long time to compute!')\n return 5\n\n ex = SlowExample()\n print(ex.hard_property)\n print(ex.hard_property)\n\n\nIn the example above, the code will take around 10 seconds to run.\nBut it only needs to take 5 seconds if the property's value is cached, like in the example below.\n\n::\n\n from jafdecs import worm\n\n @worm.onproperties\n class QuickerExample:\n @property\n def hard_property(self):\n import time\n time.sleep(5)\n print('This took a long time to compute!')\n return 5\n\n ex = QuickerExample()\n print(ex.hard_property)\n print(ex.hard_property)\n\n\nPrime a function by executing something before\n==============================================\n\nConsider a function that takes a long time to compute a value, but once it is computed it may be used over and over again.\nExploiting this reusability is the idea behind memoization.\nThe Python standard library offers the ``functools.cache()`` and ``functools.lru_cache()`` decorators.\nHowever, two limitations come to mind in use cases where memoization applies:\n\n* The returned value is very big and cannot feasibly be cached in memory\n* Programmatic control over when to pull from cache or recompute is not available\n\nFor either situation, the ``jafdecs.initialize.by(...)`` decorator can help.\nConsider the examples below.\n\n::\n\n def naive_function(path: pathlib.Path):\n # This code is somewhat complicated in that it initializes an asset before using it, unless the asset already exists.\n if not path.exists():\n print(f'File at {path} does not exist, so we will generate it before calling the actual function that needs it')\n generated_value = {}\n n = 18\n for i in range(10):\n key = str(i)\n value = i\n generated_value[key] = value\n\n print('Sleeping to simulate a hard-to-compute function.')\n time.sleep(2)\n with path.open('w') as file:\n json.dump(generated_value, file)\n\n print(f'File at {path} now exists, so we can get its data.')\n with path.open() as file:\n value = json.load(file)\n \n pprint(value)\n \n naive_function(path=pathlib.Path('example.json'))\n\n\nIn the example above, the code initializes an asset if it doesn't exist, and then uses that asset when it does.\nIf the asset already existed, it skips the initialization entirely.\nFor the sake of code cleanliness and ease of reading, the ``jafdecs.initialize.by(...)`` decorator allows these two distinct code blocks to be separated.\n\n::\n\n from jafdecs import initialize, utilities\n\n import pathlib\n import time\n import json\n from pprint import pprint\n\n\n def priming_function(path: pathlib.Path):\n print(f'File at {path} does not exist, so we will generate it before calling the actual function that needs it')\n generated_value = {}\n for i in range(10):\n key = str(i)\n value = i\n generated_value[key] = value\n\n print('Sleeping to simulate a hard-to-compute function.')\n time.sleep(2)\n with path.open('w') as file:\n json.dump(generated_value, file)\n\n\n @initialize.by(func=priming_function, condition=utilities.filenotfound)\n def actual_function(path: pathlib.Path):\n print(f'File at {path} now exists, so we can get its data.')\n with path.open() as file:\n value = json.load(file)\n \n pprint(value)\n\n\n actual_function(path=pathlib.Path('example.json'))\n actual_function(path=pathlib.Path('example.json'))\n\n\nIn the example above, the initializing code is separated in its own function, reducing the clutter in the actual function to only the code that is needed to speed things up.\nThe first execution is primed by the initializing function.\nWhen the second execution is called, no priming is needed.\nThe assets produced by the first priming are reused.\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A few useful decorators for Python functions, classes, class methods, and properties.",
"version": "0.1.0a2",
"project_urls": null,
"split_keywords": [
"decorators",
"caching",
"write once read many"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c467aa4147f73ed78494578ed804fe3d52924997171165fb2ba9666e222002f",
"md5": "d6cdfae2997430ca80274501af0f4967",
"sha256": "be0298f7e525e8349b84432fbeb141de02acbfb69b9548e6aa43bef857096e02"
},
"downloads": -1,
"filename": "jafdecs-0.1.0a2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6cdfae2997430ca80274501af0f4967",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 4533,
"upload_time": "2023-07-02T15:55:30",
"upload_time_iso_8601": "2023-07-02T15:55:30.248690Z",
"url": "https://files.pythonhosted.org/packages/8c/46/7aa4147f73ed78494578ed804fe3d52924997171165fb2ba9666e222002f/jafdecs-0.1.0a2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c6f368ffedc93cacffe4a611f8bc283503fe123273a22400c858d5ca9f4e9d6",
"md5": "3cf47165c055fea8f8a5be85f7fa256c",
"sha256": "ac10014e461196f884bc9a89805b0ed421e7fe27cfe4d22565326d9f12e3f311"
},
"downloads": -1,
"filename": "jafdecs-0.1.0a2.tar.gz",
"has_sig": false,
"md5_digest": "3cf47165c055fea8f8a5be85f7fa256c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4058,
"upload_time": "2023-07-02T15:55:31",
"upload_time_iso_8601": "2023-07-02T15:55:31.544431Z",
"url": "https://files.pythonhosted.org/packages/7c/6f/368ffedc93cacffe4a611f8bc283503fe123273a22400c858d5ca9f4e9d6/jafdecs-0.1.0a2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-02 15:55:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "jafdecs"
}
