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
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
from jscaffold import form, EnvFileVar, JsonFileVar
env = EnvFileVar("ENV", ".env").select("dev", "staging", "prod")
version = JsonFileVar("version", "package.json").indent(4)
form(env, version)
from jscaffold import form, EnvVar
file = EnvVar("FILE").local_path()
script = '''
wc -l $FILE
'''
form(file).title("Count line").run(script)
- Run requests example
- Complicated Application
- TODO
from jscaffold import form, FormPanel
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.
Remarks: You should use form
to create FormPanel instead of creating a FormPanel directly.
Example:
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"))
Set the title of the form
Example Usage:
form(var).title("Title of the form")
Configure runnables that will be executed when the form is submitted.
*args
: A list of runnable items to execute upon form submission.
Example Usage:
form().run("""
ls
""")
form().run(lambda log: log("Done"))
- Explain more
Set the label of action button (default: "Submit")
label
: The label
Example Usage:
form(var).action_label("OK")
Configure whether to save changes when the form is submitted.
value
: Boolean flag to save changes (True) or discard them (False).
Example Usage:
form().save_changes(True)
Enable or disable instant updates for the form.
value
: Boolean flag to turn instant updates on (True) or off (False).
Example Usage:
form().instant_update(True)
This class provides a wrapper for read/write environment variable.
It implemented the Formatable
and Valuable
interfaces.
The constructor:
EnvVar(key: str)
key
: The key name of the environment variable.
Example Usage:
from jscaffold import EnvVar
var = EnvVar("ENV")
print(var.value) # Read from the env var "ENV"
var.update("dev") # Set "ENV" to dev
This class provides a wrapper for read/write a field inside a JSON file. It implemented the Formatable and 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:
from jscaffold import JsonFileVar
json_var = JsonFileVar("config", "settings.json")
Set the indentation level for the JSON output.
indent
: The number of spaces used for indentation in the JSON file.
Example Usage:
json_var.indent(4)
Set the JSON path where the variable will be read or written.
value
: The path within the JSON structure.
Example Usage:
json_var.path("a.b.c")
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:
with JsonFileVar.use("data.json", indent=4):
json_var1 = JsonFileVar("version")
json_var2 = JsonFileVar("name")
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.
Initialize a Var
instance.