Skip to main content

Python shell creation library

Project description


**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

Example Shell

There is an example shell project in ``. 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

Then, install the library with

python install

Basic Use


Import Candela commands, menus, and the shell

from import Shell
from import Menu
from candela.command import Command
from candela import constants

Alternatively, you can simply `import candela` and reference the components
with ``, etc.

Subclass Shell

Every Candela app is built as a subclass of ``. A `Shell`
initialization follows this general outline:

* Set ``
* Set `self.header`
* Define and instantiate `Command`s
* Define and instantiate `Menu`s
* Add `Command`s to `Menu`s
* Set `self.menus` to contain instantiated `Menu`s
* Set `` to 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 = _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__":

Advanced Use

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
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 <>.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Candela-0.3.1.tar.gz (11.3 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page