Introduction

horetu exposes Python functions through several styles of user interfaces. The main principle behind horetu is that horetu should figures out a decent user interface based on standard Python function annotations and properties.

Install

Install from PyPI.

pip install 'horetu[all]'

Strategy for using/learning horetu

Since horetu is supposed to figure out a reasonable interface with little special configuration, you should focus first on writing conventional Python functions. Consider horetu’s special features only after your program is mostly ready.

First step

If you have not used horetu very much before, I suggest that you start by writing a function that expects str inputs and returns anything. anything or nothing, and then call one of the following functions with your function as an argument.

• horetu.cli()
• horetu.django()
• horetu.irc()
• horetu.wsgi_plain()
• horetu.wsgi_form()

Some of these functions will do nothing or produce an error because you have not specified their arguments properly; if that happens, look at the function’s documentation in the Interfaces or in the Python interpreter (with help(horetu.django), for example).

Here is an example.

import horetu
def the_function(string_input):
    return string_input.split(',')
horetu.cli(the_function)

If that mostly works for you, you can just stop here.

Further reading

If you want to change something or understand how this works, here is what you should read next.

• If you want to validate inputs, look at Input parameter annotations.
• If you want to return non-str outputs, look at Return annotations.
• If you want to display better help text, read Documentation.
• If you want to display better error messages, read Horetu exceptions and maybe Input parameter annotations.
• If you want to make a program with many sub-commands, see Subcommands.
• For considerations as to whether horetu is appropriate for a particular program, see When to use horetu.
• If you want to run horetu’s command-line interface on old versions of Python, see Similar modules.

Here is the full table of contents of the documentation.

• Interfaces
  • Command-line interface
  • Web interfaces
  • Django management command interface
  • IRC interface
  • Configuration files
  • Configuration file interfaces
• Documentation
• Horetu exceptions
• Return annotations
• Input parameter annotations
  • Concept
  • Kinds of annotations
    • Other callables
    • Annotations
    • Special objects and the empty annotation
    • Other argument characteristics sometimes matter
• Subcommands
  • Example
  • Class commands
• When to use horetu
  • Apathy regarding interface details
  • Hobby projects
  • Available interfaces
  • Python version
  • Alternatives for command-line interfaces
    • Low-level
    • Standard parser modules
    • Other modules
    • Similar modules
• Developing

Examples

For general ideas of how to use horetu, look at some examples.

Here are some short, mostly contrived, examples.

• A video of a demonstration of an old version of the command-line interface
• Examples from the tests
• Other examples included with horetu

And here are some examples from programs that I actually use.

• bguo contact manager
• scott2 regulatory permit review manager
• dadaportal static website generator
• vutwifi captive portal login

Note that many of these examples require old versions of horetu. If an example specifies, for example, version 0.3.1, then version 0.3.2 should work, but versions 0.2.1 and 0.4.0 will probably not work.

Name

Tom occasionaly bangs arbitrarily on a Dvorak keyboard in search of inspiration. One day, Horetus, the god of configuration option parsing, spoke to Tom and told him to make a module that would automatically assemble a command-line interface for specified Python functions.

After Tom implemented this command-line interface, Horetus spoke again to Tom, this time through q3k in Warsaw Hackerspace. Tom then extended horetu so it would produce a configuration file parser as well.

This sort of unanticipated extension of existing software is why Tom is wary of descriptive names for software.