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.