Candela 0.1

Python shell creation library

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

Features
--------

* Commands are 100% python and can run aribtrary code
* Commands can run code in secondary threads for asynchronous operation
* 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 `shell_example.py`. To run it, use

python shell_example.py

in a maximized terminal window.

Download
--------

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

Basic Use
---------

Importing
---------

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
with `candela.shell.Shell`, etc.

Subclass Shell
--------------

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

* Set `self.name`
* 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 `self.menu` to be the name of the default menu

Commands
--------

In general, a command instantiation looks like this

com = Command('first_command', 'Intro to commands')
def _run(*args, **kwargs):
# do anything
return constants.CHOICE_VALID
com.run = _run
return com

Functions that execute on command invocation are modeled as python first-class
functions (callbacks).

Advanced Use
------------

Please see the
[shell example](https://github.com/emmett9001/candela/blob/master/shell_example.py)
for a full walkthrough of how to use Candela. This example is both
well-commented and an instructional app demonstrating Candela's features.

Name
----

The name "Candela" was chosen after Spanish architect
[Felix Candela](http://en.wikipedia.org/wiki/F%C3%A9lix_Candela), who
pioneered the technique of building shell-shaped structures out of reinforced
concrete. He is sometimes known as the "shell builder".

Support
-------

If you need help using Candela, or have found a bug, please create an issue on
the [Github repo](https://github.com/emmett9001/candela/issues).