doc/hacking.txt

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