https://github.com/henriqueslab/ezinput
EZInput is a Python library that simplifies the creation of graphical user interfaces (GUIs) both in the terminal and in Jupyter notebooks. It provides a convenient way to add various types of widgets, making it easier to interact with your code and visualize results.
https://github.com/henriqueslab/ezinput
Last synced: 9 months ago
JSON representation
EZInput is a Python library that simplifies the creation of graphical user interfaces (GUIs) both in the terminal and in Jupyter notebooks. It provides a convenient way to add various types of widgets, making it easier to interact with your code and visualize results.
- Host: GitHub
- URL: https://github.com/henriqueslab/ezinput
- Owner: HenriquesLab
- License: mit
- Created: 2025-02-05T13:51:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-21T09:05:37.000Z (12 months ago)
- Last Synced: 2025-06-21T09:28:54.734Z (12 months ago)
- Language: Python
- Homepage: https://henriqueslab.github.io/EZInput/
- Size: 104 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# EZInput
[](https://pypi.org/project/ezinput)
[](https://python.org)
[](https://pypi.org/project/ezinput)
[](https://henriqueslab.github.io/EZInput/ezinput.html)
[](https://github.com/HenriquesLab/EZInput/blob/main/LICENSE.txt)
[](https://github.com/HenriquesLab/EZInput/actions/workflows/oncall_test.yml.yml)
[](https://img.shields.io/codecov/c/github/HenriquesLab/EZInput?branch=main)
[](https://github.com/HenriquesLab/EZInput/graphs/contributors)
[](https://github.com/HenriquesLab/EZInput/)
[](https://github.com/HenriquesLab/EZInput/)
[]()
EZInput is a Python library that simplifies the creation of user interfaces both in the terminal and in Jupyter notebooks. It provides a convenient way to add various types of widgets, making it easier to interact with your code and visualize results.
DISCLAIMER: the project is currently in alpha stage and will likely suffer changes in the API and functionality.
## Installation
To install EZInput, you can use pip:
```bash
pip install ezinput
```
## Usage
EZInput provides a unified interface for creating UIs in either the terminal or Jupyter notebooks. The mode is automatically determined based on the environment.
### Terminal Mode
To create a GUI in the terminal using `prompt_toolkit`:
```python
from ezinput import EZInput
gui = EZInput(title="My Terminal GUI")
# Add GUI elements
gui.add_check("confirm", "Do you want to proceed?", remember_value=True)
gui.add_text("name", "Enter your name:", placeholder="John Doe", remember_value=True)
gui.add_int_range("age", "Enter your age:", 18, 100, remember_value=True)
gui.add_float_range("height", "Enter your height (in meters):", 1.0, 2.5, remember_value=True)
gui.add_dropdown("color", ["Red", "Blue", "Green"], "Choose your favorite color:", remember_value=True)
gui.add_path_completer("file_path", "Enter a file path:", remember_value=True)
# Save settings
gui.save_settings()
# Restore default settings
gui.restore_default_settings()
```
### Jupyter Notebook Mode
To create a GUI in Jupyter notebooks using `ipywidgets`:
```python
from ezinput import EZInput
gui = EZInput(title="My Jupyter GUI")
# Add GUI elements
gui.add_text("text", description="Enter some text:", placeholder="Hello, world!", remember_value=True)
gui.add_int_range("int_slider", description="Choose a number:", vmin=0, vmax=10, remember_value=True)
gui.add_float_range("float_slider", description="Choose a decimal:", vmin=0.0, vmax=1.0, remember_value=True)
gui.add_check("checkbox", description="Check this box:", remember_value=True)
gui.add_dropdown("dropdown", options=["Option 1", "Option 2", "Option 3"], description="Choose an option:", remember_value=True)
gui.add_file_upload("file_upload", accept=".txt", multiple=False)
# Display the GUI
gui.show()
# Save settings
gui.save_settings()
```
### Unified API
EZInput provides a unified API for both terminal and Jupyter notebook modes. The following methods are available:
- **`add_label(tag, label)`**: Add a label to the GUI.
- **`add_text(tag, description, placeholder="", remember_value=False)`**: Add a text input field.
- **`add_text_area(tag, description, placeholder="", remember_value=False)`**: Add a multi-line text area.
- **`add_int_range(tag, description, vmin, vmax, remember_value=False)`**: Add an integer slider or range input.
- **`add_float_range(tag, description, vmin, vmax, remember_value=False)`**: Add a float slider or range input.
- **`add_check(tag, description, remember_value=False)`**: Add a yes/no or checkbox input.
- **`add_dropdown(tag, options, description="", remember_value=False)`**: Add a dropdown menu.
- **`add_callback(tag, func, values, description="Run")`**: Add a function to be ran (if in jupyter, after the press of the generated button) that triggers a callback function.
## Recent Changes
- All widget-adding methods now use the `style` from `kwargs` if provided, otherwise default to `self._style`.
- `add_custom_widget` now accepts either a widget class (which will be instantiated with `*args` and `**kwargs`) or a widget instance.
## Example: Using Custom Styles
```python
import ipywidgets as widgets
from ezinput.ezinput_jupyter import EZInputJupyter
gui = EZInputJupyter()
gui.add_text('name', description='Name:', style={'description_width': 'initial'})
```
## Example: Adding a Custom Widget
```python
# Pass a widget class (with args/kwargs)
gui.add_custom_widget('slider', widgets.IntSlider, min=0, max=10, value=5)
# Or pass an already-instantiated widget
dropdown = widgets.Dropdown(options=['A', 'B', 'C'], value='A')
gui.add_custom_widget('dropdown', dropdown)
```
### Saving and Restoring Settings
EZInput allows you to save and restore widget values using configuration files:
```python
# Save current settings
gui.save_settings()
# Restore default settings
gui.restore_default_settings()
```
### Examples
#### Terminal Example
```python
from ezinput import EZInput
gui = EZInput(title="Terminal Example")
gui.add_text("username", "Enter your username:", remember_value=True)
gui.add_int_range("age", "Enter your age:", 18, 100, remember_value=True)
gui.save_settings()
```
#### Jupyter Notebook Example
```python
from ezinput import EZInput
gui = EZInput(title="Jupyter Example")
gui.add_text("username", description="Enter your username:", remember_value=True)
gui.add_int_range("age", description="Enter your age:", vmin=18, vmax=100, remember_value=True)
gui.show()
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE.txt) file for details.