JScaffold
=========
JScaffold is a library for quickly building user interfaces in Jupyter to manipulate configuration from differnt sources (e.g .env, json) and run shell script or callback.
This project is still under development. Use it at your own risk.
**Features:**
- Common Format File Read/Write
- Read/write .env, json file
- Read/write assignment operation in several programming languages
- A Form-Based Configuration Interface
- Generate from muiltiple source (.env, json, source code)
- Auto update on changes from other Jupyter cell
# Introduction
Instead of bundling too many features into a UI and making it complicated,
it is recommended to spread the features across individual Jupyter cells,
with each cell doing just one thing. That is the design philosophy of JScaffold.
The basic element is a form that is rendered based on the types/format of the input source.
Once the submit button is pressed, it will save the changes back to the input if possible, and then run scripts/functions.
By using different forms repeatedly, an application can be built for various purposes
- [ ] Link to Demo notebook
## Examples
### Edit .env and package.json
```python
from jscaffold import form, EnvFileVar, JsonFileVar
env = EnvFileVar("ENV", ".env").select("dev", "staging", "prod")
version = JsonFileVar("version", "package.json").indent(4)
form(env, version)
```
### Pick a file and pass to a shell script
```python
from jscaffold import form, EnvVar
file = EnvVar("FILE").local_path()
script = '''
wc -l $FILE
'''
form(file).title("Count line").run(script)
```
- [ ] Run requests example
# Case Study
1. Complicated Application
- [ ] TODO
# API
## FormPanel
```python
from jscaffold import form, FormPanel
```
### form()
The `form` function serves as a shortcut for creating a FormPanel based on inputs and callback scripts or functions.
It accepts a list of Inputable objects (e.g., EnvVar, EnvFileVar, JsonFileVar), which can be passed directly as arguments or wrapped in a list.
If a string is passed, it will automatically be converted to a [Var](#var).
Remarks: You should use `form` to create FormPanel instead of creating a FormPanel directly.
Example:
```python
from jscaffold import form, EnvVar
var1 = EnvVar("VAR1")
var2 = EnvVar("VAR2")
form(var1,var2)
form([var,var2])
form("VAR3") # It is equivalent to form(Var("VAR3"))
```
### FormPanel.title(title:str)
Set the title of the form
Example Usage:
```python
form(var).title("Title of the form")
```
### FormPanel.run(*args)
Configure runnables that will be executed when the form is submitted.
- `*args`: A list of runnable items to execute upon form submission.
Example Usage:
```python
form().run("""
ls
""")
form().run(lambda log: log("Done"))
```
- [ ] Explain more
### FormPanel.action_label(label:str)
Set the label of action button (default: "Submit")
- `label`: The label
Example Usage:
```python
form(var).action_label("OK")
```
### FormPanel.save_changes(value:bool)
Configure whether to save changes when the form is submitted.
- `value`: Boolean flag to save changes (True) or discard them (False).
Example Usage:
```python
form().save_changes(True)
```
### FormPanel.instant_update(value:bool)
Enable or disable instant updates for the form.
- `value`: Boolean flag to turn instant updates on (True) or off (False).
Example Usage:
```python
form().instant_update(True)
```
## EnvVar
This class provides a wrapper for read/write environment variable.
It implemented the `Formatable` and `Valuable` interfaces.
The constructor:
```python
EnvVar(key: str)
```
- `key`: The key name of the environment variable.
Example Usage:
```python
from jscaffold import EnvVar
var = EnvVar("ENV")
print(var.value) # Read from the env var "ENV"
var.update("dev") # Set "ENV" to dev
```
## JsonFileVar
This class provides a wrapper for read/write a field inside a JSON file.
It implemented the [Formatable](#Formatable) and [Valuable](#valuable) interfaces.
The constructor:
```
JsonFileVar(key: str, filename: str)
```
- `key`: The key associated with the variable.
- `filename`: The name of the JSON file.
Example Usage:
```python
from jscaffold import JsonFileVar
json_var = JsonFileVar("config", "settings.json")
```
### JsonFileVar.indent(indent: int)
Set the indentation level for the JSON output.
- `indent`: The number of spaces used for indentation in the JSON file.
Example Usage:
```python
json_var.indent(4)
```
### JsonFileVar.path(value: str)
Set the JSON path where the variable will be read or written.
- `value`: The path within the JSON structure.
Example Usage:
```python
json_var.path("a.b.c")
```
### JsonFileVar.use(filename: str, indent=None)
A context manager for creating `JsonFileVar` instances with a common source file and optional indentation.
- `filename`: The name of the JSON file.
- `indent`: Optional indentation level for the JSON output.
Example Usage:
```python
with JsonFileVar.use("data.json", indent=4):
json_var1 = JsonFileVar("version")
json_var2 = JsonFileVar("name")
```
## Var
A Var object represents a variable that is stored in shared storage and is capable of reading and writing values. It inherits from the Valuable base class.
### Var.init(key, shared_storage: SharedStorage = shared_storage)
Initialize a `Var` instance.
Raw data
{
"_id": null,
"home_page": "https://github.com/benlau/jscaffold",
"name": "jscaffold",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "Jupyter, Widgets, IPython",
"author": "Ben lau",
"author_email": "xbenlau@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0a/d4/10921ee433280529e6c3d78d5dc67a156c65378fb5b246a8837e71770bc1/jscaffold-0.0.1.tar.gz",
"platform": "Linux",
"description": "JScaffold \n=========\n\nJScaffold is a library for quickly building user interfaces in Jupyter to manipulate configuration from differnt sources (e.g .env, json) and run shell script or callback.\n\nThis project is still under development. Use it at your own risk.\n\n**Features:**\n\n- Common Format File Read/Write\n - Read/write .env, json file\n - Read/write assignment operation in several programming languages\n- A Form-Based Configuration Interface\n - Generate from muiltiple source (.env, json, source code)\n - Auto update on changes from other Jupyter cell\n\n# Introduction\n\nInstead of bundling too many features into a UI and making it complicated, \nit is recommended to spread the features across individual Jupyter cells, \nwith each cell doing just one thing. That is the design philosophy of JScaffold.\n\n\n\nThe basic element is a form that is rendered based on the types/format of the input source. \nOnce the submit button is pressed, it will save the changes back to the input if possible, and then run scripts/functions.\n\nBy using different forms repeatedly, an application can be built for various purposes\n\n- [ ] Link to Demo notebook\n\n## Examples\n\n### Edit .env and package.json\n\n```python\nfrom jscaffold import form, EnvFileVar, JsonFileVar\nenv = EnvFileVar(\"ENV\", \".env\").select(\"dev\", \"staging\", \"prod\")\nversion = JsonFileVar(\"version\", \"package.json\").indent(4)\nform(env, version)\n```\n\n\n\n\n### Pick a file and pass to a shell script\n\n```python\nfrom jscaffold import form, EnvVar\nfile = EnvVar(\"FILE\").local_path()\nscript = '''\nwc -l $FILE\n'''\nform(file).title(\"Count line\").run(script)\n```\n\n- [ ] Run requests example\n\n# Case Study\n\n1. Complicated Application\n\n- [ ] TODO\n\n# API\n\n## FormPanel\n\n```python\nfrom jscaffold import form, FormPanel\n```\n\n### form()\n\nThe `form` function serves as a shortcut for creating a FormPanel based on inputs and callback scripts or functions.\n\nIt accepts a list of Inputable objects (e.g., EnvVar, EnvFileVar, JsonFileVar), which can be passed directly as arguments or wrapped in a list.\n\nIf a string is passed, it will automatically be converted to a [Var](#var).\n\nRemarks: You should use `form` to create FormPanel instead of creating a FormPanel directly.\n\nExample:\n\n```python\nfrom jscaffold import form, EnvVar\nvar1 = EnvVar(\"VAR1\")\nvar2 = EnvVar(\"VAR2\")\nform(var1,var2)\nform([var,var2])\nform(\"VAR3\") # It is equivalent to form(Var(\"VAR3\"))\n```\n### FormPanel.title(title:str)\n\nSet the title of the form\n\nExample Usage:\n\n```python\nform(var).title(\"Title of the form\")\n```\n\n### FormPanel.run(*args)\n\nConfigure runnables that will be executed when the form is submitted.\n\n- `*args`: A list of runnable items to execute upon form submission.\n\nExample Usage:\n\n```python\nform().run(\"\"\"\nls\n\"\"\")\n\nform().run(lambda log: log(\"Done\"))\n```\n\n- [ ] Explain more\n\n### FormPanel.action_label(label:str)\n\nSet the label of action button (default: \"Submit\") \n\n- `label`: The label\n\nExample Usage:\n\n```python\nform(var).action_label(\"OK\")\n```\n\n### FormPanel.save_changes(value:bool)\n\nConfigure whether to save changes when the form is submitted.\n\n- `value`: Boolean flag to save changes (True) or discard them (False).\n\nExample Usage:\n\n```python\nform().save_changes(True)\n```\n\n### FormPanel.instant_update(value:bool)\n\nEnable or disable instant updates for the form.\n\n- `value`: Boolean flag to turn instant updates on (True) or off (False).\n\nExample Usage:\n\n```python\nform().instant_update(True)\n```\n\n## EnvVar\n\nThis class provides a wrapper for read/write environment variable. \nIt implemented the `Formatable` and `Valuable` interfaces.\n\nThe constructor:\n\n```python\nEnvVar(key: str)\n```\n\n- `key`: The key name of the environment variable.\n\nExample Usage:\n\n```python\nfrom jscaffold import EnvVar\nvar = EnvVar(\"ENV\")\nprint(var.value) # Read from the env var \"ENV\"\nvar.update(\"dev\") # Set \"ENV\" to dev\n```\n\n## JsonFileVar\n\nThis class provides a wrapper for read/write a field inside a JSON file.\nIt implemented the [Formatable](#Formatable) and [Valuable](#valuable) interfaces.\n\nThe constructor:\n\n```\nJsonFileVar(key: str, filename: str)\n```\n\n- `key`: The key associated with the variable.\n- `filename`: The name of the JSON file.\n\nExample Usage:\n\n```python\nfrom jscaffold import JsonFileVar\njson_var = JsonFileVar(\"config\", \"settings.json\")\n```\n\n### JsonFileVar.indent(indent: int)\n\nSet the indentation level for the JSON output.\n\n- `indent`: The number of spaces used for indentation in the JSON file.\n\nExample Usage:\n\n```python\njson_var.indent(4)\n```\n\n### JsonFileVar.path(value: str)\n\nSet the JSON path where the variable will be read or written.\n\n- `value`: The path within the JSON structure.\n\nExample Usage:\n\n```python\njson_var.path(\"a.b.c\")\n```\n\n### JsonFileVar.use(filename: str, indent=None)\n\nA context manager for creating `JsonFileVar` instances with a common source file and optional indentation.\n\n- `filename`: The name of the JSON file.\n- `indent`: Optional indentation level for the JSON output.\n\nExample Usage:\n\n```python\nwith JsonFileVar.use(\"data.json\", indent=4):\n json_var1 = JsonFileVar(\"version\")\n json_var2 = JsonFileVar(\"name\")\n```\n\n## Var\n\nA Var object represents a variable that is stored in shared storage and is capable of reading and writing values. It inherits from the Valuable base class.\n\n### Var.init(key, shared_storage: SharedStorage = shared_storage)\n\nInitialize a `Var` instance.\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Jupyter Scaffold",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/benlau/jscaffold"
},
"split_keywords": [
"jupyter",
" widgets",
" ipython"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80d4c8d56840de6a2e69c2a39f28d960823f0dddaaffb896d661a8a2c7c41d79",
"md5": "204d1a21680dcaa8c446b8849f1a8922",
"sha256": "3d50d5590daa1741e350f9b9d2a4a5113469ec4987587e242081f84f8595e58a"
},
"downloads": -1,
"filename": "jscaffold-0.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "204d1a21680dcaa8c446b8849f1a8922",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 46039,
"upload_time": "2024-11-19T15:54:30",
"upload_time_iso_8601": "2024-11-19T15:54:30.427917Z",
"url": "https://files.pythonhosted.org/packages/80/d4/c8d56840de6a2e69c2a39f28d960823f0dddaaffb896d661a8a2c7c41d79/jscaffold-0.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0ad410921ee433280529e6c3d78d5dc67a156c65378fb5b246a8837e71770bc1",
"md5": "c0bc30ec97b037c3b1af729a23d2841c",
"sha256": "39bafddd14c857035e250e37e181bce676826057552d3af9e350fcf3705154fe"
},
"downloads": -1,
"filename": "jscaffold-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "c0bc30ec97b037c3b1af729a23d2841c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 32960,
"upload_time": "2024-11-19T15:54:32",
"upload_time_iso_8601": "2024-11-19T15:54:32.265705Z",
"url": "https://files.pythonhosted.org/packages/0a/d4/10921ee433280529e6c3d78d5dc67a156c65378fb5b246a8837e71770bc1/jscaffold-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 15:54:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "benlau",
"github_project": "jscaffold",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jscaffold"
}
JSON
