| Name | gearbox JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | Command line toolkit born as a PasteScript replacement for the TurboGears2 web framework |
| upload_time | 2025-02-13 20:35:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT |
| keywords |
web framework
command-line
setup
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
About gearbox
-------------------------
Gearbox is a command-line tool designed as a replacement for `paster` in TurboGears2 projects.
It originated during the effort to provide Python 3 support for TurboGears2, while maintaining
compatibility with existing projects.
Gearbox is built upon a streamlined version of the *Cliff* command-line framework. For more complex
command-line applications and custom interpreters, consider exploring `Cliff <https://cliff.readthedocs.io/en/latest/>`_.
Installing
-------------------------------
Install gearbox using pip::
pip install gearbox
Out of The Box
------------------------------
Installing gearbox provides system-wide commands for TurboGears projects, including
``gearbox serve``, ``gearbox setup-app``, and ``gearbox makepackage``. These commands
replace their `paster` counterparts.
The primary difference from `paster` is that Gearbox commands require explicit specification of the
configuration file using the ``--config`` option. By default, Gearbox loads `development.ini`.
Therefore, ``gearbox serve`` can be used instead of ``paster serve development.ini``.
To view a list of available commands, 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
patch Patches files by replacing, appending or deleting text.
For detailed help on a specific command, use ``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 development tools provides access to gearbox commands
specific to TurboGears2 project management: ``gearbox quickstart``, ``gearbox tgshell``, and
``gearbox migrate``.
The *quickstart* command is immediately available. However, project-scope plugins must be
enabled for Gearbox to recognize a TurboGears2 project and make the other two commands available.
Enabling migrate and tgshell commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable ``gearbox migrate`` and ``gearbox tgshell``, ensure that the `[project.entry-points."gearbox.plugins"]` section
in your `pyproject.toml` resembles the following:
.. code-block:: toml
[project.entry-points."gearbox.plugins"]
turbogears-devtools = "tg.devtools"
Gearbox Interactive Mode
-------------------------------
Running gearbox without a subcommand starts the interactive mode. This provides a prompt
for executing Gearbox commands, system shell commands, and Python statements. Use the
``help`` command to list available commands (``help somecommand`` provides help for a
specific command).
Gearbox HTTP Servers
------------------------------
When migrating a TurboGears2 project from `paster`, you might still be serving the
application with the Paste HTTP server even when using ``gearbox serve``.
This occurs because Gearbox uses the settings in the **server:main** section of your *.ini*
file. Projects created before TurboGears2 used Paste, so the project is likely configured
to use `Paste#http` as the server. This requires Paste to be installed. To remove the Paste
dependency, replace `Paste#http` with `gearbox#wsgiref`.
The **gearbox#wsgiref** server also supports an experimental multithreaded version, enabled by
setting `wsgiref.threaded = true` in the server configuration section.
Serving with GEvent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gearbox includes built-in support for gevent. To serve an application with Gevent, use
**gearbox#gevent** as the server in the **server:main** section of the configuration file.
The Gearbox gevent server automatically monkey patches all Python modules except for
DNS-related functions before loading the application. Ensure your code is gevent-compatible.
Scaffolding
-----------
Scaffolding creates new application components from templates.
The ``gearbox scaffold`` command creates files from scaffolds (file templates) placed within
your project. Scaffold files should have the ``.template`` extension and are used as follows::
$ gearbox scaffold templatename target
This creates a `target` file (without specifying the extension, which is defined in the
`templatename` scaffold) from the `templatename` scaffold.
A typical scaffold filename is `model.py.template` and contains:
.. code-block:: python
class {{target.capitalize()}}(DeclarativeBase):
__tablename__ = '{{target.lower()}}s'
uid = Column(Integer, primary_key=True)
data = Column(Unicode(255), nullable=False)
The scaffold command also supports looking up templates in specific paths using the `-l` or `--lookup` option,
and placing the newly created files in a specific directory using the `-p` or `--path` option.
You can also create the files in a subdirectory using the `-s` or `--subdir` option.
Patching
--------
``patch`` is a built-in Gearbox command for updating code. It functions as a Python-enhanced
`sed` command.
Examples:
Replace all `xi:include` occurrences with `py:extends` in all HTML template files recursively::
$ gearbox patch -R '*.html' xi:include -r py:extends
Update the copyright year in documentation using regular expressions and Python::
$ gearbox patch -R '*.rst' -x 'Copyright(\s*)(\d+)' -e -r '"Copyright\\g<1>"+__import__("datetime").datetime.utcnow().strftime("%Y")'
Refer to ``gearbox help patch`` for available options.
Writing new gearbox commands
----------------------------
Gearbox automatically loads commands registered as setuptools entry points under the
`[project.entry-points."gearbox.commands"]` key in `pyproject.toml`. To create a new command, subclass ``gearbox.command.Command``,
and override the `get_parser` and `take_action` methods to define custom options and behavior:
.. code-block:: python
class MyCcommand(Command):
def take_action(self, opts):
print('Hello World!')
Register the command in the `[project.entry-points."gearbox.commands"]` section of your `pyproject.toml`:
.. code-block:: toml
[project.entry-points."gearbox.commands"]
mycommand = "mypackage.commands:MyCommand"
Template Based Commands
~~~~~~~~~~~~~~~~~~~~~~~
Creating new template commands involves subclassing
**gearbox.command.TemplateCommand** within 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).
Raw data
{
"_id": null,
"home_page": null,
"name": "gearbox",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "web framework, command-line, setup",
"author": null,
"author_email": "Alessandro Molina <alessandro@molina.fyi>",
"download_url": "https://files.pythonhosted.org/packages/c8/09/ec69a0c7cae646f918669e1d604f3d956f7c1a32379b52d612f4a3f6abff/gearbox-0.3.1.tar.gz",
"platform": null,
"description": "About gearbox\n-------------------------\n\nGearbox is a command-line tool designed as a replacement for `paster` in TurboGears2 projects.\nIt originated during the effort to provide Python 3 support for TurboGears2, while maintaining\ncompatibility with existing projects.\n\nGearbox is built upon a streamlined version of the *Cliff* command-line framework. For more complex\ncommand-line applications and custom interpreters, consider exploring `Cliff <https://cliff.readthedocs.io/en/latest/>`_.\n\nInstalling\n-------------------------------\n\nInstall gearbox using pip::\n\n pip install gearbox\n\nOut of The Box\n------------------------------\n\nInstalling gearbox provides system-wide commands for TurboGears projects, including\n``gearbox serve``, ``gearbox setup-app``, and ``gearbox makepackage``. These commands\nreplace their `paster` counterparts.\n\nThe primary difference from `paster` is that Gearbox commands require explicit specification of the\nconfiguration file using the ``--config`` option. By default, Gearbox loads `development.ini`.\nTherefore, ``gearbox serve`` can be used instead of ``paster serve development.ini``.\n\nTo view a list of available commands, run ``gearbox --help``::\n\n $ gearbox --help\n usage: gearbox [--version] [-v] [--log-file LOG_FILE] [-q] [-h] [--debug]\n\n TurboGears2 Gearbox toolset\n\n optional arguments:\n --version show program's version number and exit\n -v, --verbose Increase verbosity of output. Can be repeated.\n --log-file LOG_FILE Specify a file to log output. Disabled by default.\n -q, --quiet suppress output except warnings and errors\n -h, --help show this help message and exit\n --debug show tracebacks on errors\n\n Commands:\n help print detailed help for another command\n makepackage Creates a basic python package\n migrate Handles TurboGears2 Database Migrations\n quickstart Creates a new TurboGears2 project\n serve Serves a web application that uses a PasteDeploy configuration file\n setup-app Setup an application, given a config file\n tgshell Opens an interactive shell with a TurboGears2 app loaded\n scaffold Creates a new file from a scaffold template\n patch Patches files by replacing, appending or deleting text.\n\nFor detailed help on a specific command, use ``gearbox help command``::\n\n $ gearbox help serve\n usage: gearbox serve [-h] [-n NAME] [-s SERVER_TYPE]\n [--server-name SECTION_NAME] [--daemon]\n [--pid-file FILENAME] [--reload]\n [--reload-interval RELOAD_INTERVAL] [--monitor-restart]\n [--status] [--user USERNAME] [--group GROUP]\n [--stop-daemon] [-c CONFIG_FILE]\n [args [args ...]]\n\n Serves a web application that uses a PasteDeploy configuration file\n\n positional arguments:\n args\n\n optional arguments:\n -h, --help show this help message and exit\n -n NAME, --app-name NAME\n Load the named application (default main)\n -s SERVER_TYPE, --server SERVER_TYPE\n Use the named server.\n --server-name SECTION_NAME\n Use the named server as defined in the configuration\n file (default: main)\n --daemon Run in daemon (background) mode\n --pid-file FILENAME Save PID to file (default to gearbox.pid if running in\n daemon mode)\n --reload Use auto-restart file monitor\n --reload-interval RELOAD_INTERVAL\n Seconds between checking files (low number can cause\n significant CPU usage)\n --monitor-restart Auto-restart server if it dies\n --status Show the status of the (presumably daemonized) server\n --user USERNAME Set the user (usually only possible when run as root)\n --group GROUP Set the group (usually only possible when run as root)\n --stop-daemon Stop a daemonized server (given a PID file, or default\n gearbox.pid file)\n -c CONFIG_FILE, --config CONFIG_FILE\n application config file to read (default:\n development.ini)\n\n\nDevelopment Tools Commands\n-------------------------------\n\nInstalling the TurboGears development tools provides access to gearbox commands\nspecific to TurboGears2 project management: ``gearbox quickstart``, ``gearbox tgshell``, and\n``gearbox migrate``.\n\nThe *quickstart* command is immediately available. However, project-scope plugins must be\nenabled for Gearbox to recognize a TurboGears2 project and make the other two commands available.\n\nEnabling migrate and tgshell commands\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo enable ``gearbox migrate`` and ``gearbox tgshell``, ensure that the `[project.entry-points.\"gearbox.plugins\"]` section\nin your `pyproject.toml` resembles the following:\n\n.. code-block:: toml\n\n [project.entry-points.\"gearbox.plugins\"]\n turbogears-devtools = \"tg.devtools\"\n\n\nGearbox Interactive Mode\n-------------------------------\n\nRunning gearbox without a subcommand starts the interactive mode. This provides a prompt\nfor executing Gearbox commands, system shell commands, and Python statements. Use the\n``help`` command to list available commands (``help somecommand`` provides help for a\nspecific command).\n\nGearbox HTTP Servers\n------------------------------\n\nWhen migrating a TurboGears2 project from `paster`, you might still be serving the\napplication with the Paste HTTP server even when using ``gearbox serve``.\n\nThis occurs because Gearbox uses the settings in the **server:main** section of your *.ini*\nfile. Projects created before TurboGears2 used Paste, so the project is likely configured\nto use `Paste#http` as the server. This requires Paste to be installed. To remove the Paste\ndependency, replace `Paste#http` with `gearbox#wsgiref`.\n\nThe **gearbox#wsgiref** server also supports an experimental multithreaded version, enabled by\nsetting `wsgiref.threaded = true` in the server configuration section.\n\nServing with GEvent\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nGearbox includes built-in support for gevent. To serve an application with Gevent, use\n**gearbox#gevent** as the server in the **server:main** section of the configuration file.\n\nThe Gearbox gevent server automatically monkey patches all Python modules except for\nDNS-related functions before loading the application. Ensure your code is gevent-compatible.\n\nScaffolding\n-----------\n\nScaffolding creates new application components from templates.\n\nThe ``gearbox scaffold`` command creates files from scaffolds (file templates) placed within\nyour project. Scaffold files should have the ``.template`` extension and are used as follows::\n\n $ gearbox scaffold templatename target\n\nThis creates a `target` file (without specifying the extension, which is defined in the\n`templatename` scaffold) from the `templatename` scaffold.\n\nA typical scaffold filename is `model.py.template` and contains:\n\n.. code-block:: python\n\n class {{target.capitalize()}}(DeclarativeBase):\n __tablename__ = '{{target.lower()}}s'\n\n uid = Column(Integer, primary_key=True)\n data = Column(Unicode(255), nullable=False)\n\nThe scaffold command also supports looking up templates in specific paths using the `-l` or `--lookup` option,\nand placing the newly created files in a specific directory using the `-p` or `--path` option.\nYou can also create the files in a subdirectory using the `-s` or `--subdir` option.\n\nPatching\n--------\n\n``patch`` is a built-in Gearbox command for updating code. It functions as a Python-enhanced\n`sed` command.\n\nExamples:\n\nReplace all `xi:include` occurrences with `py:extends` in all HTML template files recursively::\n\n $ gearbox patch -R '*.html' xi:include -r py:extends\n\nUpdate the copyright year in documentation using regular expressions and Python::\n\n $ gearbox patch -R '*.rst' -x 'Copyright(\\s*)(\\d+)' -e -r '\"Copyright\\\\g<1>\"+__import__(\"datetime\").datetime.utcnow().strftime(\"%Y\")'\n\nRefer to ``gearbox help patch`` for available options.\n\nWriting new gearbox commands\n----------------------------\n\nGearbox automatically loads commands registered as setuptools entry points under the\n`[project.entry-points.\"gearbox.commands\"]` key in `pyproject.toml`. To create a new command, subclass ``gearbox.command.Command``,\nand override the `get_parser` and `take_action` methods to define custom options and behavior:\n\n.. code-block:: python\n\n class MyCcommand(Command):\n def take_action(self, opts):\n print('Hello World!')\n\nRegister the command in the `[project.entry-points.\"gearbox.commands\"]` section of your `pyproject.toml`:\n\n.. code-block:: toml\n\n [project.entry-points.\"gearbox.commands\"]\n mycommand = \"mypackage.commands:MyCommand\"\n\nTemplate Based Commands\n~~~~~~~~~~~~~~~~~~~~~~~\n\nCreating new template commands involves subclassing\n**gearbox.command.TemplateCommand** within a `command.py` file in a Python package.\n\nInherit from the class and implement the *get_description*, *get_parser* and *take_action* methods\nas described by the documentation.\n\nThe only difference is that your *take_action* method has to end by calling ``self.run_template(output_dir, opts)``\nwhere *output_dir* is the directory where the template output has to be written and *opts* are the command options\nas your take_action method received them.\n\nWhen the run_template command is called Gearbox will automatically run the **template**\ndirectory in the same package where the command was available.\n\nEach file ending with the *_tmpl* syntax will be processed with the Tempita template engine and\nwhenever the name of a file or directory contains *+optname+* it will be substituted with the\nvalue of the option having the same name (e.g., +package+ will be substituted with the value\nof the --package options which will probably end being the name of the package).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command line toolkit born as a PasteScript replacement for the TurboGears2 web framework",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/TurboGears/gearbox"
},
"split_keywords": [
"web framework",
" command-line",
" setup"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fabe03f7ffa445a652b32a976070d41ded695508da8b51ae8fe5c15b7f9c0ce9",
"md5": "482586d06829719437f1f8ab586f283c",
"sha256": "3cea73d6ba904e0b979d1c84430d9401698c80ca43b1ef3343b3d5577fe38e61"
},
"downloads": -1,
"filename": "gearbox-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "482586d06829719437f1f8ab586f283c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 33425,
"upload_time": "2025-02-13T20:35:26",
"upload_time_iso_8601": "2025-02-13T20:35:26.422262Z",
"url": "https://files.pythonhosted.org/packages/fa/be/03f7ffa445a652b32a976070d41ded695508da8b51ae8fe5c15b7f9c0ce9/gearbox-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c809ec69a0c7cae646f918669e1d604f3d956f7c1a32379b52d612f4a3f6abff",
"md5": "51b2d9098fd933278f9eab5d2c362d39",
"sha256": "a62e95e7841549d9e7f7f48a8182a8496813d536dac9dee82091a7acb1b3d550"
},
"downloads": -1,
"filename": "gearbox-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "51b2d9098fd933278f9eab5d2c362d39",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33522,
"upload_time": "2025-02-13T20:35:28",
"upload_time_iso_8601": "2025-02-13T20:35:28.090858Z",
"url": "https://files.pythonhosted.org/packages/c8/09/ec69a0c7cae646f918669e1d604f3d956f7c1a32379b52d612f4a3f6abff/gearbox-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-13 20:35:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TurboGears",
"github_project": "gearbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gearbox"
}
