doc/adding-command.rst

   1 .. _adding-command:
   2
   3 Adding a new command
   4 ====================
   5
   6 ``oe`` uses the argparse_ library to implement commands. Each
   7 command lives in its own ``openerpcommand/<command>.py`` file.
   8
   9 .. _argparse: http://docs.python.org/2.7/library/argparse.html
  10
  11 To create a new command, probably the most simple way to get started is to
  12 copy/paste an existing command, say ``openerpcommand/initialize.py`` to
  13 ``openerpcommand/foo.py``. In the newly created file, the important bits
  14 are the ``run(args)`` and ``add_parser(subparsers)`` functions.
  15
  16 ``add_parser``'s responsability is to create a (sub-)parser for the command,
  17 i.e. describe the different options and flags. The last thing it does is to set
  18 ``run`` as the function to call when the command is invoked.
  19
  20 .. code-block:: python
  21
  22   > def add_parser(subparsers):
  23   >     parser = subparsers.add_parser('<command-name>',
  24   >         description='...')
  25   >     parser.add_argument(...)
  26   >     ...
  27   >     parser.set_defaults(run=run)
  28
  29 ``run(args)`` actually implements the command. It should be kept as simple as
  30 possible and delegate most of its work to small functions (probably placed at
  31 the top of the new file). In other words, its responsability is mainly to
  32 deal with the presence/absence/pre-processing of ``argparse``'s arguments.
  33
  34 Finally, the module must be added to ``openerpcommand/__init__.py``.