Metadata-Version: 1.1
Name: gearbox
Version: 0.2.2
Summary: Command line toolkit born as a PasteScript replacement for the TurboGears2 web framework
Home-page: https://github.com/TurboGears/gearbox
Author: Alessandro Molina
Author-email: amol@turbogears.org
License: MIT
Description: About gearbox
        -------------------------
        
        Gearbox is a paster command replacement for TurboGears2.
        It has been created during the process of providing Python3 support to the TurboGears2 web framework,
        while still being backward compatible with the existing TurboGears projects.
        
        Gearbox is based on a stripped down version of *Cliff* command line framework, you might want
        to consider `Cliff <http://docs.openstack.org/developer/cliff/>`_ for more advanced use cases
        and custom command interpreters.
        
        Installing
        -------------------------------
        
        gearbox can be installed from pypi::
        
            pip install gearbox
        
        should just work for most of the users
        
        Out of The Box
        ------------------------------
        
        Just by installing gearbox itself your TurboGears project will be able to use gearbox system wide
        commands like ``gearbox serve``, ``gearbox setup-app`` and ``gearbox makepackage`` commands.
        These commands provide a replacement for the paster serve, paster setup-app and paster create commands.
        
        The main difference with the paster command is usually only that gearbox commands explicitly set the
        configuration file using the ``--config`` option instead of accepting it positionally.  By default gearbox
        will always load a configuration file named `development.ini`, this mean you can simply run ``gearbox serve``
        in place of ``paster serve development.ini``
        
        To have a list of the available commands simply run ``gearbox --help``::
        
            $ gearbox --help
            usage: gearbox [--version] [-v] [--log-file LOG_FILE] [-q] [-h] [--debug]
        
            TurboGears2 Gearbox toolset
        
            optional arguments:
              --version            show program's version number and exit
              -v, --verbose        Increase verbosity of output. Can be repeated.
              --log-file LOG_FILE  Specify a file to log output. Disabled by default.
              -q, --quiet          suppress output except warnings and errors
              -h, --help           show this help message and exit
              --debug              show tracebacks on errors
        
            Commands:
              help           print detailed help for another command
              makepackage    Creates a basic python package
              migrate        Handles TurboGears2 Database Migrations
              quickstart     Creates a new TurboGears2 project
              serve          Serves a web application that uses a PasteDeploy configuration file
              setup-app      Setup an application, given a config file
              tgshell        Opens an interactive shell with a TurboGears2 app loaded
              scaffold       Creates a new file from a scaffold template
        
        Then it is possible to ask for help for a given command by using ``gearbox help command``::
        
            $ gearbox help serve
            usage: gearbox serve [-h] [-n NAME] [-s SERVER_TYPE]
                                 [--server-name SECTION_NAME] [--daemon]
                                 [--pid-file FILENAME] [--reload]
                                 [--reload-interval RELOAD_INTERVAL] [--monitor-restart]
                                 [--status] [--user USERNAME] [--group GROUP]
                                 [--stop-daemon] [-c CONFIG_FILE]
                                 [args [args ...]]
        
            Serves a web application that uses a PasteDeploy configuration file
        
            positional arguments:
              args
        
            optional arguments:
              -h, --help            show this help message and exit
              -n NAME, --app-name NAME
                                    Load the named application (default main)
              -s SERVER_TYPE, --server SERVER_TYPE
                                    Use the named server.
              --server-name SECTION_NAME
                                    Use the named server as defined in the configuration
                                    file (default: main)
              --daemon              Run in daemon (background) mode
              --pid-file FILENAME   Save PID to file (default to gearbox.pid if running in
                                    daemon mode)
              --reload              Use auto-restart file monitor
              --reload-interval RELOAD_INTERVAL
                                    Seconds between checking files (low number can cause
                                    significant CPU usage)
              --monitor-restart     Auto-restart server if it dies
              --status              Show the status of the (presumably daemonized) server
              --user USERNAME       Set the user (usually only possible when run as root)
              --group GROUP         Set the group (usually only possible when run as root)
              --stop-daemon         Stop a daemonized server (given a PID file, or default
                                    gearbox.pid file)
              -c CONFIG_FILE, --config CONFIG_FILE
                                    application config file to read (default:
                                    development.ini)
        
        
        Development Tools Commands
        -------------------------------
        
        Installing the TurboGears 2.3 development tools you will get access some some gearbox commands specific
        to TurboGears2 projects management, those are the ``gearbox quickstart``, ``gearbox tgshell`` and
        ``gearbox migrate`` commands.
        
        While the *quickstart* command will be automatically available, you will have to enable project scope plugins
        for gearbox before the other two became available. This will let gearbox know that you are running it inside
        a TurboGears2 project and so that the commands that only make sense for TurboGears2 projects will became available.
        
        Enabling migrate and tgshell commands
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        To enable ``gearbox migrate`` and ``gearbox tgshell`` commands make sure that your *setup.py* `entry_points`
        look like::
        
            entry_points={
                'paste.app_factory': [
                    'main = makonoauth.config.middleware:make_app'
                ],
                'gearbox.plugins': [
                    'turbogears-devtools = tg.devtools'
                ]
            }
        
        The **paste.app_factory** section will let ``gearbox serve`` know how to create the application that
        has to be served. Gearbox relies on PasteDeploy for application setup, so it required a paste.app_factory
        section to be able to correctly load the application.
        
        While the **gearbox.plugins** section will let *gearbox* itself know that inside that directory the tg.devtools
        commands have to be enabled making ``gearbox tgshell`` and ``gearbox migrate`` available when we run gearbox
        from inside our project directory.
        
        Gearbox Interactive Mode
        -------------------------------
        
        By default launching gearbox without any subcommand will start the interactive mode.
        This provides an interactive prompt where gearbox commands, system shell commands and python statements
        can be executed. If you have any doubt about what you can do simply run the ``help`` command to get
        a list of the commands available (running ``help somecommand`` will provide help for the given sub command).
        
        Gearbox HTTP Servers
        ------------------------------
        
        If you are moving your TurboGears2 project from paster you will probably end serving your
        application with Paste HTTP server even if you are using the ``gearbox serve`` command.
        
        The reason for this behavior is that gearbox is going to use what is specified inside
        the **server:main** section of your *.ini* file to serve your application.
        TurboGears2 projects quickstarted before 2.3 used Paste and so the projects is probably
        configured to use Paste#http as the server. This is not an issue by itself, it will just require
        you to have Paste installed to be able to serve the application, to totally remove the Paste
        dependency simply replace **Paste#http** with **gearbox#wsgiref**.
        
        The **gearbox#wsgiref** also supports an experimental multithreaded version that
        can be enabled by setting the ``wsgiref.threaded = true`` option in your server
        configuration section.
        
        Serving with GEvent
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Gearbox cames with builtin support for gevent, so serving an application under Gevent
        is just a matter of using **gearbox#gevent** as your server inside the **server:main** section
        of the configuration file.
        
        The gearbox gevent server will automatically monkeypatch all the python modules apart
        from the DNS related functions before loading your application.
        Not much more apart making sure that your code is gevent compatible is required.
        
        Scaffolding
        -----------
        
        Scaffolding is the process of creating a new component of your web application 
        through a template or preset.
        
        The ``gearbox scaffold`` command permits to create new files from scaffolds (file templates)
        which you can place inside your project itself. Scaffold files should be named with
        ``.template`` extension and can be used by running::
        
            $ gearbox scaffold templatename target
        
        This will create a ``target`` file (do not provide the extension, that is specified inside
        the templatename itself) starting from the ``templatename`` scaffold.
        
        A tipical scaffold filename will be named like ``model.py.template`` and will look like::
        
            class {{target.capitalize()}}(DeclarativeBase):
                __tablename__ = '{{target.lower()}}s'
        
                uid = Column(Integer, primary_key=True)
                data = Column(Unicode(255), nullable=False)
        
        Patching
        --------
        
        ``patch`` is one of the few builtin commands of Gearbox and is commonly used to
        update code. You can think of it as an easier to used sed command mixed with python.
        
        Here are a few examples, this will replace all xi:include occurrences
        with py:extends in all the template files recursively::
        
            $ gearbox patch -R '*.html' xi:include -r py:extends
        
        It is also possible to rely on regex and python for more complex
        replacements, like updating the Copyright year in your documentation::
        
            $ gearbox patch -R '*.rst' -x 'Copyright(\s*)(\d+)' -e -r '"Copyright\\g<1>"+__import__("datetime").datetime.utcnow().strftime("%Y")'
        
        Please refer to ``gearbox help patch`` for available options.
        
        
        Writing new gearbox commands
        ----------------------------
        
        Gearbox will automatically load any command registered as a setuptools entry point with
        ``gearbox.commands`` key. To create a new command you must subclass the ``gearbox.command.Command``
        class, override the ``get_parser`` and ``take_action`` methods to provide custom options and
        a custom behaviour::
        
            class MyCcommand(Command):
                def take_action(self, opts):
                    print('Hello World!')
        
        Then register your command in the setup.py entry points of your package::
        
            setup(name='mydistribution',
                  entry_points={
                     'gearbox.commands': [
                         'mycommand = mypackage.commands:MyCommand',
                     ]
                  })
        
        Template Based Commands
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        Writing new gearbox template commands is as simple as creating a **gearbox.command.TemplateCommand** subclass and
        place it inside a *command.py* file in a python package.
        
        Inherit from the class and implement the *get_description*, *get_parser* and *take_action* methods
        as described by the  documentation.
        
        The only difference is that your *take_action* method has to end by calling ``self.run_template(output_dir, opts)``
        where *output_dir* is the directory where the template output has to be written and *opts* are the command options
        as your take_action method received them.
        
        When the run_template command is called Gearbox will automatically run the **template**
        directory in the same package where the command was available.
        
        Each file ending with the *_tmpl* syntax will be processed with the Tempita template engine and
        whenever the name of a file or directory contains *+optname+* it will be substituted with the
        value of the option having the same name (e.g., +package+ will be substituted with the value
        of the --package options which will probably end being the name of the package).
        
Keywords: web framework command-line setup
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Framework :: TurboGears
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Classifier: Topic :: Software Development :: Libraries :: Python Modules
