Introduction ================================== .. py:module:: horetu 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 :py:class:`str` inputs and returns anything. anything or nothing, and then call one of the following functions with your function as an argument. * :py:func:`horetu.cli` * :py:func:`horetu.django` * :py:func:`horetu.irc` * :py:func:`horetu.wsgi_plain` * :py:func:`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 :ref:`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 :ref:`input-annotations`. * If you want to return non-:py:class:`str` outputs, look at :ref:`output-annotations`. * If you want to display better help text, read :ref:`documentation`. * If you want to display better error messages, read :ref:`exceptions` and maybe :ref:`input-annotations`. * If you want to make a program with many sub-commands, see :ref:`subcommands`. * For considerations as to whether horetu is appropriate for a particular program, see :ref:`alternatives`. * If you want to run horetu's command-line interface on old versions of Python, see :ref:`python2`. Here is the full table of contents of the documentation. .. toctree:: :maxdepth: 3 interfaces messages annotations subcommands alternatives developing .. _examples: 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.