Skip to content
This repository
Browse code

Add PasteDeploy dependency for serve command and write documentation

  • Loading branch information...
commit fffa11f8b771ec80e0836b057a885feeaf4aa9f2 1 parent 00bc59c
Alessandro Molina authored October 09, 2012
171  README.rst
Source Rendered
... ...
@@ -1,7 +1,9 @@
1 1
 About gearbox
2 2
 -------------------------
3 3
 
4  
-gearbox is a Python package created using the gearbox makepackage command.
  4
+gearbox is a paster command replacement for TurboGears2.
  5
+It has been created during the process of providing Python3 support to the TurboGears2 web framework,
  6
+while still being backward compatible with the existing TurboGears projects.
5 7
 
6 8
 Installing
7 9
 -------------------------------
@@ -15,3 +17,170 @@ or::
15 17
     pip install gearbox
16 18
 
17 19
 should just work for most of the users
  20
+
  21
+Out of The Box
  22
+------------------------------
  23
+
  24
+Just by installing gearbox itself your TurboGears project will be able to use gearbox system wide
  25
+commands like ``gearbox serve``, ``gearbox setup-app`` and ``gearbox basic_package`` commands.
  26
+These commands provide a replacement for the paster serve, paster setup-app and paster create commands.
  27
+
  28
+To have a list of the available commands simply run ``gearbox --help``::
  29
+
  30
+    $ gearbox --help
  31
+    usage: gearbox [--version] [-v] [--log-file LOG_FILE] [-q] [-h] [--debug]
  32
+
  33
+    TurboGears2 Gearbox toolset
  34
+
  35
+    optional arguments:
  36
+      --version            show program's version number and exit
  37
+      -v, --verbose        Increase verbosity of output. Can be repeated.
  38
+      --log-file LOG_FILE  Specify a file to log output. Disabled by default.
  39
+      -q, --quiet          suppress output except warnings and errors
  40
+      -h, --help           show this help message and exit
  41
+      --debug              show tracebacks on errors
  42
+
  43
+    Commands:
  44
+      help           print detailed help for another command
  45
+      makepackage    Creates a basic python package
  46
+      migrate        Handles TurboGears2 Database Migrations
  47
+      quickstart     Creates a new TurboGears2 project
  48
+      serve          Serves a web application that uses a PasteDeploy configuration file
  49
+      setup-app      Setup an application, given a config file
  50
+      tgshell        Opens an interactive shell with a TurboGears2 app loaded
  51
+
  52
+
  53
+Then it is possible to ask for help for a given command by using ``gearbox help command``::
  54
+
  55
+    $ gearbox help serve
  56
+    usage: gearbox serve [-h] [-n NAME] [-s SERVER_TYPE]
  57
+                         [--server-name SECTION_NAME] [--daemon]
  58
+                         [--pid-file FILENAME] [--reload]
  59
+                         [--reload-interval RELOAD_INTERVAL] [--monitor-restart]
  60
+                         [--status] [--user USERNAME] [--group GROUP]
  61
+                         [--stop-daemon]
  62
+                         [args [args ...]]
  63
+
  64
+    Serves a web application that uses a PasteDeploy configuration file
  65
+
  66
+    positional arguments:
  67
+      args
  68
+
  69
+    optional arguments:
  70
+      -h, --help            show this help message and exit
  71
+      -n NAME, --app-name NAME
  72
+                            Load the named application (default main)
  73
+      -s SERVER_TYPE, --server SERVER_TYPE
  74
+                            Use the named server.
  75
+      --server-name SECTION_NAME
  76
+                            Use the named server as defined in the configuration
  77
+                            file (default: main)
  78
+      --daemon              Run in daemon (background) mode
  79
+      --pid-file FILENAME   Save PID to file (default to gearbox.pid if running in
  80
+                            daemon mode)
  81
+      --reload              Use auto-restart file monitor
  82
+      --reload-interval RELOAD_INTERVAL
  83
+                            Seconds between checking files (low number can cause
  84
+                            significant CPU usage)
  85
+      --monitor-restart     Auto-restart server if it dies
  86
+      --status              Show the status of the (presumably daemonized) server
  87
+      --user USERNAME       Set the user (usually only possible when run as root)
  88
+      --group GROUP         Set the group (usually only possible when run as root)
  89
+      --stop-daemon         Stop a daemonized server (given a PID file, or default
  90
+                            gearbox.pid file)
  91
+
  92
+
  93
+
  94
+Development Tools Commands
  95
+-------------------------------
  96
+
  97
+Installing the TurboGears 2.3 development tools you will get access some some gearbox commands specific
  98
+to TurboGears2 projects management, those are the ``gearbox quickstart``, ``gearbox tgshell`` and
  99
+``gearbox migrate`` commands.
  100
+
  101
+While the *quickstart* command will be automatically available, you will have to enable project scope plugins
  102
+for gearbox before the other two became available. This will let gearbox know that you are running it inside
  103
+a TurboGears2 project and so that the commands that only make sense for TurboGears2 projects will became available.
  104
+
  105
+Enabling migrate and tgshell commands
  106
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  107
+
  108
+To enable ``gearbox migrate`` and ``gearbox tgshell`` commands make sure that your *setup.py* `entry_points`
  109
+look like::
  110
+
  111
+    entry_points={
  112
+        'paste.app_factory': [
  113
+            'main = makonoauth.config.middleware:make_app'
  114
+        ],
  115
+        'gearbox.plugins': [
  116
+            'turbogears-devtools = tg.devtools'
  117
+        ]
  118
+    }
  119
+
  120
+The **paste.app_factory** section will let ``gearbox serve`` know how to create the application that
  121
+has to be served. Gearbox relies on PasteDeploy for application setup, so it required a paste.app_factory
  122
+section to be able to correctly load the application.
  123
+
  124
+While the **gearbox.plugins** section will let *gearbox* itself know that inside that directory the tg.devtools
  125
+commands have to be enabled making ``gearbox tgshell`` and ``gearbox migrate`` available when we run gearbox
  126
+from inside our project directory.
  127
+
  128
+Gearbox Interactive Mode
  129
+-------------------------------
  130
+
  131
+By default launching gearbox without any subcommand will start the interactive mode.
  132
+This provides an interactive prompt where gearbox commands, system shell commands and python statements
  133
+can be executed. If you have any doubt about what you can do simply run the ``help`` command to get
  134
+a list of the commands available (running ``help somecommand`` will provide help for the given sub command).
  135
+
  136
+Gearbox HTTP Servers
  137
+------------------------------
  138
+
  139
+If you are moving your TurboGears2 project from paster you will probably end serving your
  140
+application with Paste HTTP server even if you are using the ``gearbox serve`` command.
  141
+
  142
+The reason for this behavior is that gearbox is going to use what is specified inside
  143
+the **server:main** section of your *.ini* file to serve your application.
  144
+TurboGears2 projects quickstarted before 2.3 used Paste and so the projects is probably
  145
+configured to use Paste#http as the server. This is not an issue by itself, it will just require
  146
+you to have Paste installed to be able to serve the application, to totally remove the Paste
  147
+dependency simply replace **Paste#http** with **gearbox#wsgiref**.
  148
+
  149
+Serving with GEvent
  150
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  151
+
  152
+Gearbox cames with builtin support for gevent, so serving an application under Gevent
  153
+is just a matter of using **gearbox#gevent** as your server inside the **server:main** section
  154
+of the configuration file.
  155
+
  156
+The gearbox gevent server will automatically monkeypatch all the python modules apart
  157
+from the DNS related functions before loading your application.
  158
+Not much more apart making sure that your code is gevent compatible is required.
  159
+
  160
+Writing new gearbox commands
  161
+---------------------------------
  162
+
  163
+gearbox relies on the Cliff command framework for commands crations. Most of what
  164
+the `Cliff <https://cliff.readthedocs.org/en/latest/>`_ documentation states is perfectly
  165
+valid for gearbox commands, some differences only apply in the case of *Template based commands*.
  166
+
  167
+Template Based Commands
  168
+~~~~~~~~~~~~~~~~~~~~~~~~
  169
+
  170
+Writing new gearbox template commands is as simple as creating a **gearbox.command.TemplateCommand** subclass and
  171
+place it inside a *command.py* file in a python package.
  172
+
  173
+Inherit from the class and implement the *get_description*, *get_parser* and *take_action* methods
  174
+as described by the  documentation.
  175
+
  176
+The only difference is that your *take_action* method has to end by calling ``self.run_template(output_dir, opts)``
  177
+where *output_dir* is the directory where the template output has to be written and *opts* are the command options
  178
+as your take_action method received them.
  179
+
  180
+When the run_template command is called Gearbox will automatically run the **template**
  181
+directory in the same package where the command was available.
  182
+
  183
+Each file ending with the *_tmpl* syntax will be processed with the Tempita template engine and
  184
+whenever the name of a file or directory contains *+optname+* it will be substituted with the
  185
+value of the option having the same name (e.g., +package+ will be substituted with the value
  186
+of the --package options which will probably end being the name of the package).
2  gearbox/main.py
@@ -10,8 +10,6 @@ def __init__(self):
10 10
         super(GearBox, self).__init__(description="TurboGears2 Gearbox toolset", 
11 11
                                       version='2.3',
12 12
                                       command_manager=CommandManager('gearbox.commands'))
13  
-
14  
-        print('Loading local commands...')
15 13
         self._load_commands_for_current_dir()
16 14
 
17 15
     def _load_commands_for_current_dir(self):
3  setup.py
@@ -24,7 +24,8 @@
24 24
       zip_safe=False,
25 25
       install_requires=[
26 26
         "cliff",
27  
-        "tempita"
  27
+        "tempita",
  28
+        "PasteDeploy"
28 29
       ],
29 30
       entry_points={
30 31
         'console_scripts': [

0 notes on commit fffa11f

Please sign in to comment.
Something went wrong with that request. Please try again.