Candela is a simple shell-building system that uses python and curses to help developers create customized command line interfaces. It has a simple interface, is well documented, and allows developers to take command-based tools to the next level of complexity and usability.
This is free software, and you are welcome to redistribute it under certain conditions. See the free software definition for details
- Commands are 100% python and can run aribtrary code
- Commands can run code in secondary threads for asynchronous operation
- Customizable tab completion hooks for command arguments
- Customizable key event callbacks for reacting to each keypress event
- Responsive layout for smaller terminals
- Numerous built-in command templates
- Simple command syntax and help system
- "stickers" allow persistent information display
- Automatically generated command validation
- Up/Down arrows cycle through history
- Copy/Paste, insert text mode
- Easy transitions between menus
- Supports both named and positional command arguments
There is an example shell project in
shell_example.py. To run it, use
in a maximized terminal window.
Download the source from PyPI with
pip install candela
You can also clone this repo to take a closer look at the code and demo app.
git clone https://github.com/emmett9001/candela.git
Then, install the library with
python setup.py install
First thing's first: if you really want to understand how to use Candela,
read the code! There's a lot of documentation with code examples for the
more complicated parts. A good starting point would be
Import Candela commands, menus, and the shell
from candela.shell import Shell from candela.menu import Menu from candela.command import Command from candela import constants
Alternatively, you can simply
import candela and reference the components
Every Candela app is built as a subclass of
initialization follows this general outline:
- Define and instantiate
- Define and instantiate
self.menusto contain instantiated
self.menuto be the name of the default menu
In general, a command instantiation looks like this
com = Command('first_command an_arg <-f reqd_arg>', 'Intro to commands') def _run(*args, **kwargs): # do anything return constants.CHOICE_VALID com.run = _run
Functions that execute on command invocation are modeled as python first-class functions (callbacks).
Running the Shell
Once you've set up some commands and menus, you can create a runnable python script with your shell by using
if __name__ == "__main__": MyShell().main_loop().end()
Please see the shell example for a full walkthrough of how to use Candela. This example is both well-commented and an instructional app demonstrating Candela's features.
The name "Candela" was chosen after Spanish architect Felix Candela, who pioneered the technique of building shell-shaped structures out of reinforced concrete. He is sometimes known as the "shell builder".
If you need help using Candela, or have found a bug, please create an issue on the Github repo.
This file is part of Candela. Candela is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Candela is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Candela. If not, see <http://www.gnu.org/licenses/>.