[](https://stakk.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/aastopher/stakk)
[](https://app.deepsource.com/gh/aastopher/stakk/?ref=repository-badge)
## Description
Stakk is designed to stack functions into a register, the registered stack is designed to be consumed by a stack of modular utilities. This pattern is intended to facilitate a lower barrier for entry to configure command line interfaces, benchmark tasks, and manage threaded agents.
***
## Quick Start:
## register functions with stakk
Using the register decorator `@stakk.register('stack_id')` on your functions will register it with a stack in `meta_handler.Stack`. Functions in a stack are available for utilities to register and create a link to the stack.
```python
import stakk
@stakk.register('stack_id')
def add(x : int, y : int):
'''add two integers'''
return x + y
```
You can also register async functions, these will be executed using `asyncio.run()` given a valid coroutine function.
```python
import stakk
import asyncio
@stakk.register('stack_id')
async def delay_add(x : int, y : int):
'''add two integers after 1 sec'''
await asyncio.sleep(1)
return x + y
```
## cli - initialization standard
It is suggested to define the command line interface after `if __name__ == '__main__'`. Any code before the cli will run even if a cli command is used; code after the cli definition will not run when passing a cli command. The cli initialization will require 1 argument a stack_id, optionally you can provide a description it is suggested to use doc strings for this and init as shown.
```python
import stakk
# registered functions...
# module level function calls...
if __name__ == '__main__':
# main code (will run even when using cli commands)...
stakk.cli(stack_id = 'stack_id', desc = __doc__) # desc is optional
# main code (will NOT run when using cli commands)...
```
## cli - args and optional args
Adding a default value will create an optional arg for the command. The keyword and default value will be displayed in the help docs along with the type if one is given.
```python
"""This module does random stuff."""
import stakk
@stakk.register('cli')
def meet(name : str, greeting : str = 'hello', farewell : str = 'goodbye') -> str:
'''meet a person'''
return f'\n{greeting} {name}\n{farewell} {name}'
# module level function calls...
if __name__ == '__main__':
# main code (will run even when using cli commands)...
stakk.cli(stack_id = 'cli', desc = __doc__)
# main code (will NOT run when using cli commands)...
```
**NOTE:** Adding type hinting to your functions enforces types in the cli and adds positional arg class identifiers in the help docs for that command.
**Command usage:**
```
python module.py meet foo
```
**Output:**
```
hello foo
goodbye foo
```
**Module help output:**
```
usage: module [-h] {meet} ...
This module does random stuff.
options:
-h, --help show this help message and exit
commands:
{meet}
meet meet a person
```
**Command help output:**
```
usage: module meet [-gr GREETING] [-fa FAREWELL] [-h] name
meet(name: str, greeting: str = 'hello', farewell: str = 'goodbye') -> str
positional arguments:
name type: str
options:
-gr GREETING, --greeting GREETING
type: str, default: hello
-fa FAREWELL, --farewell FAREWELL
type: str, default: goodbye
-h, --help Show this help message and exit.
```
## cli - choice arguments
Adding an iterable as the type annotation will define a choices argument. A custom type checker is defined based on the option types in the iterable provided. This will allow you to define mixed types in your choices lists.
```python
"""This module does random stuff."""
import stakk
foo_choices = ['foo', 'fooo','foooo']
bar_choices = ('bar', 1, 'baar', 2)
@stakk.register('cli')
def foo_choices(foo: foo_choices, bar: bar_choices = 2) -> tuple:
'''foo bar'''
return foo, bar
# module level function calls...
if __name__ == '__main__':
# main code (will run even when using cli commands)...
stakk.cli(stack_id = 'cli', desc = __doc__)
# main code (will NOT run when using cli commands)...
```
**Command usage:**
```
python module.py foo_choices fooo --bar 1
```
**Output:**
```
('fooo', 1)
```
**Command help output:**
```
usage: module foo_choices [-ba BAR] [-h] foo
foo_choices(foo: choice_type, bar: choice_type = 2) -> tuple
positional arguments:
foo choices: (foo, fooo, foooo)
options:
-ba BAR, --bar BAR choices: (bar, 1, baar, 2), default: 2
-h, --help Show this help message and exit.
```
## cli - list annotation
Using list as a type annotation has special context. This will prompt the cli to define a custom list type which returns `re.split(r'[;,| ]', value)`. This allows you to specify string with delimiters which are converted to lists before being passed to the function. You are welcome to create and pass your own type functions but lists are built in for ease of use.
```python
"""This module does random stuff."""
import stakk
@stakk.register('cli')
def foo_lists(foo : list, bar : list = ['foo','bar']) -> tuple:
return foo, bar
# module level function calls...
if __name__ == '__main__':
# main code (will run even when using cli commands)...
stakk.cli(stack_id = 'cli', desc = __doc__)
# main code (will NOT run when using cli commands)...
```
**Command usage:**
```
python module.py foo_lists 'foo,bar;foo|bar foo'
```
**Output:**
```
(['foo', 'bar', 'foo', 'bar', 'foo'], ['foo', 'bar'])
```
**Command help output:**
```
usage: module foo_lists [-ba BAR] [-h] foo
foo_lists(foo: type_list, bar: type_list = ['foo', 'bar']) -> tuple
positional arguments:
foo type: list
options:
-ba BAR, --bar BAR type: list, default: ['foo', 'bar']
-h, --help Show this help message and exit.
```
## cli - variadic functions
Variadic functions are compatible with stakk cli utility. When calling kwargs from the cli; `key=value` should be used instead of `--` and `-`, these are reserved for default arguments.
**NOTE:** providing type annotations will enforce type, however this will apply to all `*args` or `**kwargs`, if custom logic is needed you can create and pass a custom type function.
```python
"""This module does random stuff."""
import stakk
@stakk.register('cli')
def variadic(*args: str, **kwargs: int):
print("Positional arguments:")
for arg in args:
print(arg)
print("Keyword arguments:")
for key, value in kwargs.items():
print(f"{key} = {value}")
# module level function calls...
if __name__ == '__main__':
# main code (will run even when using cli commands)...
stakk.cli(stack_id = 'cli', desc = __doc__)
# main code (will NOT run when using cli commands)...
```
**Command usage:**
```
python module.py variadic foo bar foo foo=1 bar=2
```
**Output:**
```
Positional arguments:
foo
bar
foo
Keyword arguments:
foo = 1
bar = 2
```
**Command help output:**
```
usage: dev variadic [-h] [*args ...] [**kwargs ...]
variadic(args, kwargs)
positional arguments:
*args ex: command arg1 arg2
**kwargs ex: command key=value
options:
-h, --help Show this help message and exit.
```
## benchy - usage example
The `benchy` decorator is designed to collect performance timing and call info for selected functions. This can be used in combination with `@stakk.register`, the decorators are order independent.
```python
import stakk
import asyncio
@stakk.benchy
@stakk.register('test_stack')
def add(x : int, y : int):
'''add two integers'''
return x + y
@stakk.register('test_stack')
@stakk.benchy
def subtract(x : int, y : int):
'''subtract two integers'''
return x - y
@stakk.benchy
@stakk.register('test_stack')
def calc(x : int, y : int, atype : str = '+') -> int:
'''calculates a thing'''
if atype == '+':
res = add(x, y)
elif atype == '-':
res = subtract(x, y)
return res
@stakk.register('test_stack')
@stakk.benchy
async def async_example():
'''An example async function'''
await asyncio.sleep(1)
print("Async function completed.")
add(1,2)
add(2,2)
subtract(1,2)
calc(2,3, atype='-')
asyncio.get_event_loop().run_until_complete(async_example())
```
After the functions have been executed, the benchmark report can be accessed with `stakk.benchy.report`.
```python
# print the benchmark report
print(stakk.benchy.report)
```
Example output:
```
{
'add': [
{
'args': [{'type': 'int', 'value': 1}, {'type': 'int', 'value': 2}],
'benchmark': 0.00015466799959540367,
'kwargs': None,
'result': {'type': 'int', 'value': 3}
},
{
'args': [{'type': 'int', 'value': 2}, {'type': 'int', 'value': 2}],
'benchmark': 6.068096263334155e-05,
'kwargs': None,
'result': {'type': 'int', 'value': 4}
}
],
'calc': [
{
'args': [{'type': 'int', 'value': 2}, {'type': 'int', 'value': 3}],
'benchmark': 4.855601582676172e-05,
'kwargs': {'atype': {'length': 1, 'type': 'str'}},
'result': {'type': 'int', 'value': 5}
}
],
'subtract': [
{
'args': [{'type': 'int', 'value': 1}, {'type': 'int', 'value': 2}],
'benchmark': 5.205394700169563e-05,
'kwargs': None,
'result': {'type': 'int', 'value': -1}
}
],
'async_example': [
{
'args': None,
'benchmark': 1.001522845996078,
'kwargs': None,
'result': {'type': 'NoneType', 'value': None}
}
]
}
```
The output of the benchmark report will adhere to the following format. `function : call report`. Call reports consist of `{args, kwargs, result, benchmark}` there will be a record for each call of a given function.
**NOTE:** given an iterable for `arg`, `kwarg`, or `result` the object will be summarized in terms of vector length.
```
{
'function_name': [
{
'args': [{'type': 'arg_type', 'value': int}],
'benchmark': float,
'kwargs': {'kwarg_name': {'type': 'arg_type', 'length': int}},
'result': {'type': 'arg_type', 'value': float}
}
]
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aastopher/stakk",
"name": "stakk",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "agent,worker,threading,cli,utils,performance counter,benchmark",
"author": "Aaron Stopher",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/fd/ca/dff499ec372720d3feedab58396c72510794b26135bbd24bd80eb7c9b0c2/stakk-0.1.0.tar.gz",
"platform": null,
"description": "[](https://stakk.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/aastopher/stakk)\n[](https://app.deepsource.com/gh/aastopher/stakk/?ref=repository-badge)\n\n## Description\n\nStakk is designed to stack functions into a register, the registered stack is designed to be consumed by a stack of modular utilities. This pattern is intended to facilitate a lower barrier for entry to configure command line interfaces, benchmark tasks, and manage threaded agents.\n***\n\n## Quick Start:\n\n## register functions with stakk\n\nUsing the register decorator `@stakk.register('stack_id')` on your functions will register it with a stack in `meta_handler.Stack`. Functions in a stack are available for utilities to register and create a link to the stack.\n\n```python\nimport stakk\n\n@stakk.register('stack_id')\ndef add(x : int, y : int):\n '''add two integers'''\n return x + y\n```\n\nYou can also register async functions, these will be executed using `asyncio.run()` given a valid coroutine function.\n\n```python\nimport stakk\nimport asyncio\n\n@stakk.register('stack_id')\nasync def delay_add(x : int, y : int):\n '''add two integers after 1 sec'''\n await asyncio.sleep(1)\n return x + y\n```\n\n## cli - initialization standard\n\nIt is suggested to define the command line interface after `if __name__ == '__main__'`. Any code before the cli will run even if a cli command is used; code after the cli definition will not run when passing a cli command. The cli initialization will require 1 argument a stack_id, optionally you can provide a description it is suggested to use doc strings for this and init as shown.\n\n```python\nimport stakk\n\n# registered functions...\n\n# module level function calls...\n\nif __name__ == '__main__':\n # main code (will run even when using cli commands)...\n stakk.cli(stack_id = 'stack_id', desc = __doc__) # desc is optional\n # main code (will NOT run when using cli commands)...\n```\n\n## cli - args and optional args\n\nAdding a default value will create an optional arg for the command. The keyword and default value will be displayed in the help docs along with the type if one is given.\n\n```python\n\"\"\"This module does random stuff.\"\"\"\nimport stakk\n\n@stakk.register('cli')\ndef meet(name : str, greeting : str = 'hello', farewell : str = 'goodbye') -> str:\n '''meet a person'''\n return f'\\n{greeting} {name}\\n{farewell} {name}'\n\n# module level function calls...\n\nif __name__ == '__main__':\n # main code (will run even when using cli commands)...\n stakk.cli(stack_id = 'cli', desc = __doc__)\n # main code (will NOT run when using cli commands)...\n```\n\n**NOTE:** Adding type hinting to your functions enforces types in the cli and adds positional arg class identifiers in the help docs for that command.\n\n**Command usage:**\n\n```\npython module.py meet foo\n```\n\n**Output:**\n\n```\nhello foo\ngoodbye foo\n```\n\n**Module help output:**\n\n```\nusage: module [-h] {meet} ...\n\nThis module does random stuff.\n\noptions:\n-h, --help show this help message and exit\n\ncommands:\n{meet}\n meet meet a person\n```\n\n**Command help output:**\n\n```\nusage: module meet [-gr GREETING] [-fa FAREWELL] [-h] name\n\nmeet(name: str, greeting: str = 'hello', farewell: str = 'goodbye') -> str\n\npositional arguments:\nname type: str\n\noptions:\n-gr GREETING, --greeting GREETING\n type: str, default: hello\n-fa FAREWELL, --farewell FAREWELL\n type: str, default: goodbye\n-h, --help Show this help message and exit.\n```\n\n## cli - choice arguments\n\nAdding an iterable as the type annotation will define a choices argument. A custom type checker is defined based on the option types in the iterable provided. This will allow you to define mixed types in your choices lists.\n\n```python\n\"\"\"This module does random stuff.\"\"\"\nimport stakk\n\nfoo_choices = ['foo', 'fooo','foooo']\nbar_choices = ('bar', 1, 'baar', 2)\n\n@stakk.register('cli')\ndef foo_choices(foo: foo_choices, bar: bar_choices = 2) -> tuple:\n '''foo bar'''\n return foo, bar\n\n# module level function calls...\n\nif __name__ == '__main__':\n # main code (will run even when using cli commands)...\n stakk.cli(stack_id = 'cli', desc = __doc__)\n # main code (will NOT run when using cli commands)...\n```\n\n**Command usage:**\n\n```\npython module.py foo_choices fooo --bar 1\n```\n\n**Output:**\n\n```\n('fooo', 1)\n```\n\n**Command help output:**\n\n```\nusage: module foo_choices [-ba BAR] [-h] foo\n\nfoo_choices(foo: choice_type, bar: choice_type = 2) -> tuple\n\npositional arguments:\nfoo choices: (foo, fooo, foooo)\n\noptions:\n-ba BAR, --bar BAR choices: (bar, 1, baar, 2), default: 2\n-h, --help Show this help message and exit.\n```\n\n## cli - list annotation\n\nUsing list as a type annotation has special context. This will prompt the cli to define a custom list type which returns `re.split(r'[;,| ]', value)`. This allows you to specify string with delimiters which are converted to lists before being passed to the function. You are welcome to create and pass your own type functions but lists are built in for ease of use.\n\n```python\n\"\"\"This module does random stuff.\"\"\"\nimport stakk\n\n@stakk.register('cli')\ndef foo_lists(foo : list, bar : list = ['foo','bar']) -> tuple:\n return foo, bar\n\n# module level function calls...\n\nif __name__ == '__main__':\n # main code (will run even when using cli commands)...\n stakk.cli(stack_id = 'cli', desc = __doc__)\n # main code (will NOT run when using cli commands)...\n```\n\n**Command usage:**\n\n```\npython module.py foo_lists 'foo,bar;foo|bar foo'\n```\n\n**Output:**\n\n```\n(['foo', 'bar', 'foo', 'bar', 'foo'], ['foo', 'bar'])\n```\n\n**Command help output:**\n\n```\nusage: module foo_lists [-ba BAR] [-h] foo\n\nfoo_lists(foo: type_list, bar: type_list = ['foo', 'bar']) -> tuple\n\npositional arguments:\nfoo type: list\n\noptions:\n-ba BAR, --bar BAR type: list, default: ['foo', 'bar']\n-h, --help Show this help message and exit.\n```\n\n## cli - variadic functions\n\nVariadic functions are compatible with stakk cli utility. When calling kwargs from the cli; `key=value` should be used instead of `--` and `-`, these are reserved for default arguments.\n\n**NOTE:** providing type annotations will enforce type, however this will apply to all `*args` or `**kwargs`, if custom logic is needed you can create and pass a custom type function.\n\n```python\n\"\"\"This module does random stuff.\"\"\"\nimport stakk\n\n@stakk.register('cli')\ndef variadic(*args: str, **kwargs: int):\n \n print(\"Positional arguments:\")\n\n\n for arg in args:\n print(arg)\n\n print(\"Keyword arguments:\")\n for key, value in kwargs.items():\n print(f\"{key} = {value}\")\n\n# module level function calls...\n\nif __name__ == '__main__':\n # main code (will run even when using cli commands)...\n stakk.cli(stack_id = 'cli', desc = __doc__)\n # main code (will NOT run when using cli commands)...\n```\n\n**Command usage:**\n\n```\npython module.py variadic foo bar foo foo=1 bar=2\n```\n\n**Output:**\n\n```\nPositional arguments:\nfoo\nbar\nfoo\n\nKeyword arguments:\nfoo = 1\nbar = 2\n```\n\n**Command help output:**\n\n```\nusage: dev variadic [-h] [*args ...] [**kwargs ...]\n\nvariadic(args, kwargs)\n\npositional arguments:\n*args ex: command arg1 arg2\n**kwargs ex: command key=value\n\noptions:\n-h, --help Show this help message and exit.\n```\n\n## benchy - usage example\n\nThe `benchy` decorator is designed to collect performance timing and call info for selected functions. This can be used in combination with `@stakk.register`, the decorators are order independent.\n\n```python\nimport stakk\nimport asyncio\n\n@stakk.benchy\n@stakk.register('test_stack')\ndef add(x : int, y : int):\n '''add two integers'''\n return x + y\n\n@stakk.register('test_stack')\n@stakk.benchy\ndef subtract(x : int, y : int):\n '''subtract two integers'''\n return x - y\n\n@stakk.benchy\n@stakk.register('test_stack')\ndef calc(x : int, y : int, atype : str = '+') -> int:\n '''calculates a thing'''\n if atype == '+':\n res = add(x, y)\n elif atype == '-':\n res = subtract(x, y)\n return res\n\n@stakk.register('test_stack')\n@stakk.benchy\nasync def async_example():\n '''An example async function'''\n await asyncio.sleep(1)\n print(\"Async function completed.\")\n\nadd(1,2)\nadd(2,2)\nsubtract(1,2)\ncalc(2,3, atype='-')\nasyncio.get_event_loop().run_until_complete(async_example())\n```\n\nAfter the functions have been executed, the benchmark report can be accessed with `stakk.benchy.report`.\n\n```python\n# print the benchmark report\nprint(stakk.benchy.report)\n```\n\nExample output:\n\n```\n{\n 'add': [\n {\n 'args': [{'type': 'int', 'value': 1}, {'type': 'int', 'value': 2}],\n 'benchmark': 0.00015466799959540367,\n 'kwargs': None,\n 'result': {'type': 'int', 'value': 3}\n },\n {\n 'args': [{'type': 'int', 'value': 2}, {'type': 'int', 'value': 2}],\n 'benchmark': 6.068096263334155e-05,\n 'kwargs': None,\n 'result': {'type': 'int', 'value': 4}\n }\n ],\n 'calc': [\n {\n 'args': [{'type': 'int', 'value': 2}, {'type': 'int', 'value': 3}],\n 'benchmark': 4.855601582676172e-05,\n 'kwargs': {'atype': {'length': 1, 'type': 'str'}},\n 'result': {'type': 'int', 'value': 5}\n }\n ],\n 'subtract': [\n {\n 'args': [{'type': 'int', 'value': 1}, {'type': 'int', 'value': 2}],\n 'benchmark': 5.205394700169563e-05,\n 'kwargs': None,\n 'result': {'type': 'int', 'value': -1}\n }\n ],\n 'async_example': [\n {\n 'args': None,\n 'benchmark': 1.001522845996078,\n 'kwargs': None,\n 'result': {'type': 'NoneType', 'value': None}\n }\n ]\n}\n```\n\nThe output of the benchmark report will adhere to the following format. `function : call report`. Call reports consist of `{args, kwargs, result, benchmark}` there will be a record for each call of a given function.\n\n**NOTE:** given an iterable for `arg`, `kwarg`, or `result` the object will be summarized in terms of vector length.\n\n```\n{\n 'function_name': [\n {\n 'args': [{'type': 'arg_type', 'value': int}],\n 'benchmark': float,\n 'kwargs': {'kwarg_name': {'type': 'arg_type', 'length': int}},\n 'result': {'type': 'arg_type', 'value': float}\n }\n ]\n}\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Stakk is designed to stack functions into a register, this registered stack is designed to be consumed by a stack of modular utilities.",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/aastopher/stakk/issues",
"Documentation": "https://stakk.readthedocs.io",
"Homepage": "https://github.com/aastopher/stakk"
},
"split_keywords": [
"agent",
"worker",
"threading",
"cli",
"utils",
"performance counter",
"benchmark"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8487c2101c01048c75a1ea720d3389f443b9a8f5b68b2cb1104e2f06843328b5",
"md5": "525a9526e60a73e82487914078eb3d8e",
"sha256": "82702e4663260d2929b59512d5cc4db94c8e41390c7393a3469b28d3cd381107"
},
"downloads": -1,
"filename": "stakk-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "525a9526e60a73e82487914078eb3d8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10256,
"upload_time": "2023-08-15T21:22:49",
"upload_time_iso_8601": "2023-08-15T21:22:49.580458Z",
"url": "https://files.pythonhosted.org/packages/84/87/c2101c01048c75a1ea720d3389f443b9a8f5b68b2cb1104e2f06843328b5/stakk-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fdcadff499ec372720d3feedab58396c72510794b26135bbd24bd80eb7c9b0c2",
"md5": "a7741a9b20ae64206c6ecc99ca18dfd2",
"sha256": "c6e64eb529be45b1da5a88e1b16dfb82849663b69e7b9b6684731a3435c47a56"
},
"downloads": -1,
"filename": "stakk-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a7741a9b20ae64206c6ecc99ca18dfd2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15390,
"upload_time": "2023-08-15T21:22:50",
"upload_time_iso_8601": "2023-08-15T21:22:50.996549Z",
"url": "https://files.pythonhosted.org/packages/fd/ca/dff499ec372720d3feedab58396c72510794b26135bbd24bd80eb7c9b0c2/stakk-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-15 21:22:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aastopher",
"github_project": "stakk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "stakk"
}
JSON
