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`.
  44 :class:`~hooke.hooke.Hooke` reads in the configuration files and loads
  45 Plugins_ and Drivers_.  Then it forks off a
  46 :class:`~hooke.engine.CommandEngine` instance to execute Commands_,
  47 and a :class:`~hooke.ui.UserInterface` instance to connect the
  48 :class:`~hooke.engine.CommandEngine` with the user.  The
  49 :class:`~hooke.engine.CommandEngine` runs in a subprocess, which
  50 allows command execution to occur in parallel with
  51 :class:`~hooke.ui.UserInterface` interaction.  The two processes
  52 communicate via two :class:`~multiprocessing.Queue`\s.
  53
  54 There are a number of special classes availiable to structure queue
  55 communications.  See :mod:`~hooke.interaction` and
  56 :class:`~hooke.command.CommandExit` for details.
  57
  58 Plugins
  59 -------
  60
  61 :class:`~hooke.plugin.Plugin`\s contain bundles of Commands_,
  62 representing the various operations a user can carry out through the
  63 Hooke interface.
  64
  65 :class:`~hooke.plugin.Plugin`\s can depend on other
  66 :class:`~hooke.plugin.Plugin`\s, so you shouldn't need to repeat code.
  67 One central :class:`~hooke.plugin.Plugin` can provide useful
  68 functionality to several dependent :class:`~hooke.plugin.Plugin`\s.
  69
  70 There is a :class:`~hooke.plugin.Plugin` subtype
  71 :class:`~hooke.plugin.Builtin` which is just like a
  72 :class:`~hooke.plugin.Plugin`, but is considered fundamental enough to
  73 not be optional.  :class:`~hooke.plugin.Builtin`\s are always loaded.
  74
  75 Commands
  76 ~~~~~~~~
  77
  78 :class:`~hooke.command.Command`\s specify user-actions in an
  79 interface-agnostic manner.  This makes writing
  80 :class:`~hooke.ui.UserInterface`\s easier, because you don't need to
  81 know anything about particular :class:`~hooke.plugin.Plugin`\s or
  82 :class:`~hooke.command.Command`\s, you just need to be able to explain
  83 the base classes for you user and then speak the language of
  84 :mod:`~hooke.interaction` and :class:`~hooke.command.CommandExit` with
  85 the :class:`~hooke.engine.CommandEngine` process.
  86
  87 Drivers
  88 -------
  89
  90 :class:`~hooke.driver.Driver`\s are responsible for reading assorted
  91 data files into Hooke's Data_ structure.
  92
  93 Data
  94 ----
  95
  96 Experiments
  97 ~~~~~~~~~~~
  98
  99 Force spectroscopy experiments come in several major flavors.  Each
 100 flavor gets its own subclass of :class:`~hooke.experiment.Experiment`
 101 in :mod:`~hooke.experiment`.  For example, force clamp experiments are
 102 :class:`~hooke.experiment.ForceClamp`.  This gives Drivers_ a way to
 103 tag experimental data so Commands_ know what they are working with.
 104
 105 Curves
 106 ~~~~~~
 107
 108 Experiments_ tags need a data-holding container to tag, and
 109 :class:`~hooke.curve.Curve`\s are that container.  Each
 110 :class:`~hooke.curve.Curve` can hole several blocks of
 111 :class:`~hooke.curve.Data` (for example approach and retract curves in
 112 a :class:`~hooke.experiment.VelocityClamp` experiment would be
 113 seperate blocks).  :class:`~hooke.curve.Curve`\s also have an
 114 :attr:`~hooke.curve.Curve.info` attribute for persistently storing
 115 arbitrary data.
 116
 117 Playlists
 118 ~~~~~~~~~
 119
 120 Normally you'll want to analyze multiple Curves_ in one session.
 121 :class:`~hooke.playlist.Playlist`\s provide a convenient container for
 122 Curves_, and the subclass :class:`~hooke.playlist.FilePlaylist` add
 123 persistant file backing (save, load, etc.).
 124
 125 Utilities
 126 ---------
 127
 128 There are a number of general coding features we need for Hooke that
 129 are not provided by Python's standard library.  We factor those
 130 features out into :mod:`~hooke.util`.
 131
 132 There are also a number of features who's standard library support
 133 changes with different versions of Python.  :mod:`~hooke.compat`
 134 provides a uniform interface to those tools so that Hooke will work
 135 with several Python versions.