{"id":13419920,"url":"https://github.com/SimonBiggs/scriptedforms","last_synced_at":"2025-03-15T06:30:49.445Z","repository":{"id":53169145,"uuid":"96386447","full_name":"SimonBiggs/scriptedforms","owner":"SimonBiggs","description":"Quickly create live-update GUIs for Python packages using Markdown and simple HTML elements.","archived":true,"fork":false,"pushed_at":"2022-09-27T22:50:38.000Z","size":7846,"stargazers_count":508,"open_issues_count":105,"forks_count":34,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-08-31T12:39:04.048Z","etag":null,"topics":["angular-material","jupyter","jupyterlab-extension","markdown"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SimonBiggs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-06T03:55:12.000Z","updated_at":"2024-03-10T19:11:16.000Z","dependencies_parsed_at":"2022-09-14T09:41:18.018Z","dependency_job_id":null,"html_url":"https://github.com/SimonBiggs/scriptedforms","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonBiggs%2Fscriptedforms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonBiggs%2Fscriptedforms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonBiggs%2Fscriptedforms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonBiggs%2Fscriptedforms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SimonBiggs","download_url":"https://codeload.github.com/SimonBiggs/scriptedforms/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221548140,"owners_count":16840979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular-material","jupyter","jupyterlab-extension","markdown"],"created_at":"2024-07-30T22:01:22.857Z","updated_at":"2024-10-26T15:30:57.444Z","avatar_url":"https://github.com/SimonBiggs.png","language":"TypeScript","readme":"\u003c!-- markdownlint-disable MD033 --\u003e\n\n# Scripted Forms [![Build Status](https://travis-ci.org/SimonBiggs/scriptedforms.svg?branch=master)](https://travis-ci.org/SimonBiggs/scriptedforms) [![Sauce Test Status](https://saucelabs.com/buildstatus/ScriptedForms)](https://saucelabs.com/u/ScriptedForms) [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/SimonBiggs/scriptedforms-examples/master?urlpath=scriptedforms/use/detailed-example.md)\n\n## Project Archived\n\nThis project has been archived. This was created back in Febuary 2018. Since then\n[Streamlit](https://github.com/streamlit/streamlit/blob/develop/README.md) has\nbeen created and has built a brilliant library, company and community\nand is going on to success upon success.\n\nPlease use Streamlit as a replacement for ScriptedForms.\n\n## Overview\n\nMaking GUIs easy for everyone on your team.\n\nThe primary benefit is that front ends for Python code become easily accessible\nto everyone on your team. Easy to use, easy to update, easy to extend, and easy\nto understand.\n\n* Quickly create live-update GUIs for Python packages using Markdown and a few custom HTML elements.\n* Just write in markdown + variables / UI types\n* Based on Jupyter\n\n## Development stage\n\nThis is currently in alpha stage development. Expect bugs, expect the experience to be rough around the edges at times. There are still significant changes in store for this library before it is ready to be classified as beta. However, I do encourage you to take it for a spin and journey with me, influencing what this will become.\n\n## Quick start\n\nTo use ScriptedForms you will need Python (\u003e=3.5) on your computer. A platform independent way to install Python is to [download and install the Anaconda Python distribution](https://www.anaconda.com/download).\n\nOnce you have Python on your computer installing\nScriptedForms is as simple as typing the following into a terminal (or command prompt):\n\n```bash\npip install scriptedforms\n```\n\nThen to use it create a markdown file within your current directory called `quick-start.md` with any plaintext editor (such as\n[Visual Studio Code](https://code.visualstudio.com/)).\nMake the contents be the following:\n\n~~~markdown\n# An example\n\n\u003csection-live\u003e\n\n\u003cvariable-string\u003eyour_name\u003c/variable-string\u003e\n\n```python\nprint('Hello {}!'.format(your_name))\n```\n\n\u003c/section-live\u003e\n~~~\n\nThen run the following in your terminal\n\n```bash\nscriptedforms quick-start.md\n```\n\nIf everything worked, a Scripted Form should open within your default browser.\nYou should be able to type your name into the form and see the code field live\nupdate with each key stroke:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/quick-start.png\"\u003e\n\u003c/p\u003e\n\nNow within `quick-start.md` edit the markdown file by changing\n\n```markdown\n# An example\n```\n\nto\n\n```markdown\n# The form updates when I change it\n```\n\nand then press save. The form in the browser should then update to match what\nyou just wrote.\n\n### Plotting and slider example\n\nIf you want to be a bit more adventurous see what happens if you add the\nfollowing to the end of the your `quick-start.md` file (or any other\nScriptedForm):\n\n~~~markdown\n#### Example slider use case\n\nUsing the slider and live sections combined with matplotlib plots you can\nproduce utilities like the following:\n\n\u003csection-start onLoad\u003e\n\n```python\nt = np.linspace(-2*np.pi, 2*np.pi, 500)\nomega = np.ones(2)\n```\n\n\u003c/section-start\u003e\n\n\u003csection-live\u003e\n\nAngular frequencies ($\\omega$):\n\n\u003cvariable-slider label=\"$\\omega [0]$\" min=\"0\" max=\"6\" step=\"0.1\"\u003eomega[0]\u003c/variable-slider\u003e\n\u003cvariable-slider label=\"$\\omega [1]$\" min=\"0\" max=\"6\" step=\"0.1\"\u003eomega[1]\u003c/variable-slider\u003e\n\n```python\nplt.figure(figsize=(5*1.618,5))\n\noscillation = np.sin(t[:, np.newaxis] * omega[np.newaxis, :])\nsummation = np.sum(oscillation, axis=1)\n\nplt.plot(t, oscillation)\nplt.plot(t, summation)\n\nplt.xlim([-2*np.pi, 2*np.pi])\nplt.ylim([-2.4, 2.4])\nplt.title('Two sin curves and their summation')\nplt.legend([\n    r'$\\omega [0] = {0:0.1f}$'.format(omega[0]),\n    r'$\\omega [1] = {0:0.1f}$'.format(omega[1]),\n    'Summation'], loc='upper right')\nplt.xlabel('time (seconds)')\nplt.ylabel(r'$sin(\\omega \\times t)$');\n```\n\n\u003c/section-live\u003e\n~~~\n\nThis should produce what is seen in the following screenshot:\n\n\u003ca href=\"https://mybinder.org/v2/gh/SimonBiggs/scriptedforms-examples/master?urlpath=scriptedforms/use/plotting-example.md\"\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"./images/detailed.png\"\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n[Click here](https://mybinder.org/v2/gh/SimonBiggs/scriptedforms-examples/master?urlpath=scriptedforms/use/plotting-example.md) to see a live version of this example on mybinder.org. This will run slower online on that server than when you are using it locally.\n\n### More features\n\nFor a markdown file that presents the majority of the features of scriptedforms\nsee\n[detailed.form.md](https://raw.githubusercontent.com/SimonBiggs/scriptedforms/master/detailed.form.md).\nTry writing some of the contents of that file into a ScriptedForm to see how\nthey work.\n\n## Platform/browser testing matrix\n\nThe following OS Browser combinations are explicitly tested using [Sauce Labs](https://saucelabs.com):\n\n[![Sauce Test Status](https://saucelabs.com/browser-matrix/ScriptedForms.svg)](https://saucelabs.com/u/ScriptedForms)\n\n## Security notice\n\nBe aware that ScriptedForms uses the [Jupyter Notebook Server security model](http://jupyter-notebook.readthedocs.io/en/stable/security.html#security-in-the-jupyter-notebook-server). When a user has access to the forms via the localhost web interface, should they have sufficient know how, they also have the ability to run arbitrary Python code without limitations.\n\nBy default only users on the local machine will be able to access the Jupyter Notebook Server which means if you trust a user to run code on their own machine then allowing them to use ScriptedForms will not cause issue. Only override these default settings if you understand and accept the security implications.\n\nFurthermore do not run a scripted form unless you trust its origin. Given the reactive nature of ScriptedForms, code within the markdown template can run on form opening, as well as during usage.\n\n\u003c!-- ## Example that can be used as a template for deployment\n\nThis is designed to be used as a quick and easy GUI for python packages. An\nexample package that creates a console script that then uses scriptedforms to\nboot up a GUI can be found within the [example](./example) directory.\n\nWithin the [`README.md`](./example/README.md) file of that directory there is an\nexplanation of how you might go about deploying your utility with its new GUI. --\u003e\n\n\u003c!-- ## [Optional] Installing the Jupyter Server extension\n\nScriptedForms can also be installed as a [Jupyter Server extension](http://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Distributing%20Jupyter%20Extensions%20as%20Python%20Packages.html#Enable-a-Server-Extension). Eventually this should allow the use of ScriptedForms with tools such as [JupyterHub](http://jupyterhub.readthedocs.io/en/latest/). This part of ScriptedForms is still a work in progress but if you want to give it a try then make sure you have at least version `0.5.15` of ScriptedForms and then run:\n\n```bash\njupyter serverextension enable --py scriptedforms\n```\n\nThen to start ScriptedForms using its Jupyter Server extension run the following\n\n```bash\njupyter notebook --NotebookApp.default_url=/scriptedforms/use/quick-start.md\n``` --\u003e\n\n## [Advanced users only] Installing scriptedforms from the GitHub source\n\nThe majority of users will not need to pay attention to this section.\n\nFor those who wish to build scriptedforms from the source provided within this\nrepository, instead of using pypi, the javascript bundle will need to be built.\nTo do this you will need to\n[install `yarn`](https://yarnpkg.com/lang/en/docs/install/) and then run the\nfollowing in the\n[directory containing the `package.json` file](./scriptedforms):\n\n```bash\nyarn\nyarn build\nyarn pip:install\n```\n\nThis will install the node packages, build the javascript files and then run\n`pip install -e .` to install the python package.\n\n\n### License Change\n\nI have re-released this code base under the Apache-2.0 license so that it may\nbe freely used within other projects without needing to adhere to the copyleft\nrequirements of the AGPL. The comments below regarding the previous choice of\nlicense will be left unchanged.\n\n\n### Justification for using a copyleft license\n\nI desire to seed a Medical Physics open source community within Australia.\nMedical Physicists have been repeatedly blocked from giving code to the\ncommunity. There may be an opportunity for sharing however if there is an\nexisting IP agreement that distributed code or modifications will be\nprovided under the same license.\n\nAs such, to be able to seed a Medical Physics open source community within\nAustralia I need to create something that helps Medical Physicists write their\ncode and have it licensed under a copyleft license.\n\nI hope this is that package.\n\nFor more information on why you as a Medical Physicist might want to use the\nAGPL-3.0+ license read the [benefits of AGPL-3.0+ for Medical Physics](./Benefits-of-AGPL-3.0+-for-Medical-Physics.md).\n\n### Justification for the inclusion of additional terms\n\nA significant and justifiable fear within the Medical Physics community is that\nshould code be shared the author of the code may be liable for negligence. As\nsuch specifically addressing negligence within the additional terms is a must\nif this code base will become a seed to create a Medical Physics open source\ncommunity in Australia.\n\nWithin Australian courts if there is any ambiguity in liability exclusion\nclauses they will be interpreted narrowly. If liability for negligence is not\nexpressly excluded it may not be read as excluded within an Australian court\n(\u003chttps://eprints.qut.edu.au/7404/1/open_source_book.pdf\u003e page 80).\nThe same is true for clauses which seek to exclude liability for consequential\nloss.\n\nThe AGPL-3.0+ does not explicitly mention negligence anywhere within its\nlicense text. The Apache-2.0 does. The AGPL-3.0+ in Section 7 does define\nallowable additional terms. The negligence clauses within the Apache-2.0 fall\nunder these allowable additional terms so, as such, they have been included.\n\nThere are also other desirable features of the Apache-2.0 license such as\ncontribution, trademark, and warranty requirements. These were also included.\n\n### A note about the code sharing license requirement\n\nIf you only ever use this code internally within your company to create GUIs\nthe only people who need to have access to the source code are those users\nwhom you distribute the program to. Therefore you do not need to share your\ncode outside of your company if your only users are within your company.\n\nHowever there are significant benefits from sharing your code with the\ncommunity. Please read the [benefits of AGPL-3.0+ for Medical Physics](./Benefits-of-AGPL-3.0+-for-Medical-Physics.md).\n","funding_links":[],"categories":["TypeScript","Uncategorized","markdown"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimonBiggs%2Fscriptedforms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSimonBiggs%2Fscriptedforms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimonBiggs%2Fscriptedforms/lists"}