doc/hacking.txt

   1 *************
   2 Hacking Hooke
   3 *************
   4
   5 .. toctree::
   6    :maxdepth: 2
   7
   8    testing.txt
   9
  10 Dependencies
  11 ============
  12
  13 To clean up the internals, were going to go crazy on the
  14 object-oriented front, and try to keep the core functionality free of
  15 any dependencies other than the `Python Standard Library`_ and Numpy_
  16 / Scipy_.
  17
  18 .. _Python Standard Library: http://docs.python.org/library/
  19 .. _Numpy: http://numpy.scipy.org/
  20 .. _Scipy: http://www.scipy.org/
  21
  22 To make a responsive user interface in parallel with data processing
  23 and possible GUIs, we'll use Python's multiprocessing_ module.  This
  24 module is new in Python 2.6, but 2.6 usage is becoming fairly
  25 widespread.  Certainly more widespread than any alternative queue
  26 module that I know of.  Since we're leveraging the power of the
  27 standard library, we use configparser_ for the config files.
  28
  29 .. _multiprocessing: http://docs.python.org/dev/library/multiprocessing.html
  30 .. _configparser: http://docs.python.org/library/configparser.html
  31
  32 On the testing side, the need to stick to the standard library relaxes
  33 (developers can install extra packages), so we can use nose_.  See
  34 the Testing_ section for more information.
  35
  36 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.3/
  37 .. _Testing: testing.txt
  38
  39
  40 Architecture
  41 ============
  42
  43 Hooke's main entry point is :class:`hooke.hooke.Hooke`.  `Hooke` reads
  44 in the configuration files and loads Plugins_ and Drivers_.  Then it
  45 forks off a :class:`hooke.engine.CommandEngine` instance to execute
  46 Commands_, and a :class:`hooke.ui.UserInterface` instance to connect
  47 the `CommandEngine` with the user.  The `CommandEngine` runs in a
  48 subprocess, which allows command execution to occur in parallel with
  49 `UserInterface` interaction.  The two processes communicate via two
  50 :class:`multiprocessing.Queue`\s.
  51
  52 There are a number of special classes availiable to structure queue
  53 communications.  See :mod:`hooke.interaction` and
  54 :class:`hooke.command.CommandExit` for details.
  55
  56 Plugins
  57 -------
  58
  59 :class:`hooke.plugin.Plugin`\s contain bundles of Commands_,
  60 representing the various operations a user can carry out through the
  61 Hooke interface.
  62
  63 `Plugin`\s can depend on other `Plugin`\s, so you shouldn't need to
  64 repeat code.  One central `Plugin` can provide useful functionality
  65 to several dependent `Plugin`\s.
  66
  67 There is a `Plugin` subtype :class:`hooke.plugin.Builtin` which is
  68 just like a `Plugin`, but is considered fundamental enough to not be
  69 optional.  `Builtin`\s are always loaded.
  70
  71 Commands
  72 ~~~~~~~~
  73
  74 :class:`hooke.command.Command`\s specify user-actions in an
  75 interface-agnostic manner.  This makes writing
  76 :class:`hooke.ui.UserInterface`\s easier, because you don't need to
  77 know anything about particular `Plugin`\s or `Command`\s, you just
  78 need to be able to explain the base classes for you user and then
  79 speak the language of :mod:`hooke.interaction` and
  80 :class:`hooke.command.CommandExit` with the
  81 :class:`hooke.engine.CommandEngine` process.
  82
  83 Drivers
  84 -------
  85
  86 :class:`hooke.driver.Driver`\s are responsible for reading assorted
  87 data files into Hooke's Data_ structure.
  88
  89 Data
  90 ----
  91
  92 Experiments
  93 ~~~~~~~~~~~
  94
  95 Force spectroscopy experiments come in several major flavors.  Each
  96 flavor gets its own subclass of :class:`hooke.experiment.Experiment`
  97 in :mod:`hooke.experiment`.  For example, force clamp experiments are
  98 :class:`hooke.experiment.ForceClamp`.  This gives Drivers_ a way to
  99 tag experimental data so Commands_ know what they are working with.
 100
 101 Curves
 102 ~~~~~~
 103
 104 Experiments_ tags need a data-holding container to tag, and
 105 :class:`hooke.curve.Curve`\s are that container.  Each `Curve` can
 106 hole several blocks of :class:`hooke.curve.Data` (for example approach
 107 and retract curves in a :class:`hooke.experiment.VelocityClamp`
 108 experiment would be seperate blocks).  `Curve`\s also have an
 109 :attr:`~hooke.curve.Curve.info` attribute for persistently storing
 110 arbitrary data.
 111
 112 Playlists
 113 ~~~~~~~~~
 114
 115 Normally you'll want to analyze multiple Curves_ in one session.
 116 :class:`hooke.playlist.Playlist`\s provide a convenient container for
 117 Curves_, and the subclass :class:`hooke.playlist.FilePlaylist` add
 118 persistant file backing (save, load, etc.).
 119
 120 Utilities
 121 ---------
 122
 123 There are a number of general coding features we need for Hooke that
 124 are not provided by Python's standard library.  We factor those
 125 features out into :mod:`hooke.utils`.
 126
 127 There are also a number of features who's standard library support
 128 changes with different versions of Python.  :mod:`hooke.compat`
 129 provides a uniform interface to those tools so that Hooke will work
 130 with several Python versions.