= Command-Line Scripting =

== Accessing `hou` from a Regular Python Shell ==

By simply importing the `hou` module into a regular Python shell, you can
easily integrate Houdini into your existing Python-based scripts.  The first
time you import `hou`, Python will load in all of Houdini's libraries and
initialize an empty Houdini session.  The `hou` module effectively stores a
Houdini session, and you can load into that session from a hip file, inspect
that file from your script, and input and output information to and from nodes
in that sesssion.

In order to import the `hou` module, you need to tell Python to search in
`$HFS/houdini/scripts/python` for Python modules.  One way to accomplish this
is to append this to the PYTHONPATH environment variable before starting
Python, and another is to append the path to the `sys.path` from within Python.
The following Python snippet will import the `hou` module into a standard
Python shell, assuming that you sourced houdini_setup to set $HFS.

{{{
#!python
#!/usr/bin/python2.5
import sys, os
sys.path.append(os.environ['HFS'] + "/houdini/scripts/python")
import hou
}}}

When you import the `hou` module, Python will check out a license.  By
default, it will use a Houdini Batch license, and use a Houdini Master
license if no batch license could be found.  If you want it to use a
Houdini Escape license, you can set the HOUDINI_SCRIPT_LICENSE variable
to "hescape" before importing the hou module.  You can also set this
variable from within your Python script with
`os.environ['HOUDINI_SCRIPT_LICENSE'] = 'hescape'`.

By default, the `hou` module will not return the Houdini license until the
Python interpreter exits.  However, if you have a long running Python
script and want to quickly acquire and release a license, you can call
[Hom:hou.releaseLicense] when you are done with the `hou` module.  Subsequent
calls into the `hou` module will reacquire the license.  Note that Houdini's
session data and libraries will not be unloaded from memory until Python exits.

The `hou` module, when imported by Python or Houdini, will loop through the
directories in $HOUDINI_SCRIPT_PATH, and for each directory found, append
that directory plus "/python" to sys.path.  Also note that
$HOUDINI_SCRIPT_PATH defaults to the directories in $HOUDINI_PATH with
an additional "/scripts" suffix.  For example, if you use the default
$HOUDINI_PATH, importing `hou` will append
`$HOME/houdiniX.Y/scripts/python` to Python sys.path.

=== hython ===

Hython is a Python shell that ships with Houdini that is slightly
different from the standard Python shell in the following ways:
- It automatically adds `$HFS/houdini/scripts/python` to sys.path and
  imports the hou module when it starts up.
- You can pass .hip files on the command line and it will load them.
- It supports tab completion, and you can press tab twice to list possible
  completions.
- It can receive and handle Houdini openport commands while waiting for console
  input.