gearbox 0.2.2

关于gearbox

Gearbox是TurboGears2的paster命令替代品。它是在为TurboGears2网络框架提供Python3支持的过程中创建的，同时仍然与现有的TurboGears项目保持向后兼容。

Gearbox基于一个简化版的Cliff命令行框架，对于更高级的使用场景和自定义命令解释器，您可能想考虑Cliff。

安装

gearbox可以从PyPI安装

pip install gearbox

对大多数用户来说应该可以正常工作

即装即用

只需安装齿轮箱本身，您的TurboGears项目就可以使用齿轮箱的全局命令，如 gearbox serve、gearbox setup-app 和 gearbox makepackage 命令。这些命令为 paster serve、paster setup-app 和 paster create 命令提供了替代方案。

与paster命令的主要区别通常只是齿轮箱命令明确使用 --config 选项设置配置文件，而不是按位置接受它。默认情况下，齿轮箱将始终加载一个名为 development.ini 的配置文件，这意味着您可以简单地运行 gearbox serve 来代替 paster serve development.ini

要获取可用命令的列表，只需运行 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

然后可以通过使用 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)

开发工具命令

安装TurboGears 2.3开发工具后，您将能够访问一些专门针对TurboGears2项目管理的一些齿轮箱命令，这些是 gearbox quickstart、gearbox tgshell 和 gearbox migrate 命令。

虽然 quickstart 命令将自动可用，但在其他两个命令可用之前，您必须启用齿轮箱的项目范围插件。这将让齿轮箱知道您正在TurboGears2项目中运行，从而使仅对TurboGears2项目有意义的命令变得可用。

entry_points={
    'paste.app_factory': [
        'main = makonoauth.config.middleware:make_app'
    ],
    'gearbox.plugins': [
        'turbogears-devtools = tg.devtools'
    ]
}

齿轮箱交互模式

默认情况下，在没有子命令的情况下启动齿轮箱将启动交互模式。这提供了一个交互式提示，可以在其中执行齿轮箱命令、系统shell命令和Python语句。如果您有任何疑问，只需运行 help 命令即可获取可用命令的列表（运行 help somecommand 将提供给定子命令的帮助）。

齿轮箱HTTP服务器

如果您正在将TurboGears2项目从paster迁移，那么您可能会使用Paste HTTP服务器来提供应用程序，即使您正在使用 gearbox serve 命令。

这种行为的原因是齿轮箱将使用您在 .ini 文件的 server:main 部分中指定的内容来提供您的应用程序。在2.3之前快速启动的TurboGears2项目使用了Paste，因此项目可能配置为使用Paste#http作为服务器。这本身不是问题，但您将需要安装Paste来提供应用程序，要完全删除Paste依赖，只需将 Paste#http 替换为 gearbox#wsgiref。

gearbox#wsgiref 还支持一个实验性的多线程版本，可以通过在服务器配置部分设置 wsgiref.threaded = true 选项来启用。

脚手架

脚手架是通过模板或预设创建您的 Web 应用程序新组件的过程。

使用 gearbox scaffold 命令，您可以从脚手架（文件模板）创建新文件，并将这些文件放置在您的项目内部。脚手架文件应以 .template 扩展名命名，并可以通过运行以下命令使用：

$ gearbox scaffold templatename target

这将从一个 templatename 脚手架创建一个 target 文件（不要提供扩展名，它已在模板名称中指定）。

一个典型的脚手架文件名可能像 model.py.template，其内容可能如下所示：

class {{target.capitalize()}}(DeclarativeBase):
    __tablename__ = '{{target.lower()}}s'

    uid = Column(Integer, primary_key=True)
    data = Column(Unicode(255), nullable=False)

修补

patch 是 Gearbox 的几个内置命令之一，通常用于更新代码。您可以将它视为比 sed 命令更易于使用的 sed 命令与 Python 的混合体。

以下是一些示例，此命令将递归地替换所有模板文件中的 xi:include 出现为 py:extends

$ gearbox patch -R '*.html' xi:include -r py:extends

还可以依赖于正则表达式和 Python 进行更复杂的替换，例如更新文档中的版权年份

$ gearbox patch -R '*.rst' -x 'Copyright(\s*)(\d+)' -e -r '"Copyright\\g<1>"+__import__("datetime").datetime.utcnow().strftime("%Y")'

有关可用选项，请参阅 gearbox help patch。

编写新的 gearbox 命令

Gearbox 会自动加载任何以 gearbox.commands 键注册为 setuptools entry point 的命令。要创建新命令，您必须从 gearbox.command.Command 类派生，并覆盖 get_parser 和 take_action 方法以提供自定义选项和自定义行为。

class MyCcommand(Command):
    def take_action(self, opts):
        print('Hello World!')

然后，在您的包的 setup.py 入口点中注册您的命令

setup(name='mydistribution',
      entry_points={
         'gearbox.commands': [
             'mycommand = mypackage.commands:MyCommand',
         ]
      })