rattail.commands.base

Console Commands - base classes and core commands

class rattail.commands.base.ArgumentParser(*args, **kwargs)

Custom argument parser.

This is a compatibility wrapper around upstream wuttjamaican:wuttjamaican.commands.base.CommandArgumentParser. New code should use that instead; this will eventually be removed.

class rattail.commands.base.CheckDatabase(*args, **kwargs)

Do basic sanity checks on a Rattail DB

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.CloneDatabase(*args, **kwargs)

Clone (supported) data from a source DB to a target DB

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

rattail.commands.base.Command

alias of RattailCommand

class rattail.commands.base.EmailBouncer(*args, **kwargs)

Interacts with the email bouncer daemon. This command expects a subcommand; one of the following:

• rattail bouncer start

• rattail bouncer stop

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.FileMonitorCommand(*args, **kwargs)

Interacts with the file monitor service; called as rattail filemon. This command expects a subcommand; one of the following:

• rattail filemon start

• rattail filemon stop

On Windows platforms, the following additional subcommands are available:

• rattail filemon install

• rattail filemon uninstall (or rattail filemon remove)

Note

The Windows Vista family of operating systems requires you to launch cmd.exe as an Administrator in order to have sufficient rights to run the above commands.

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.MailMonitorCommand(*args, **kwargs)

Interacts with the mail monitor service; called as rattail mailmon. This command expects a subcommand; one of the following:

• rattail mailmon start

• rattail mailmon stop

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.MakeConfig(*args, **kwargs)

Generate stub config file(s) where you want them

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.MakeUUID(*args, **kwargs)

Generate a new UUID

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.MakeUser(*args, **kwargs)

Create a new user account in a given system

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.PalmCommand(*args, **kwargs)

Manages registration for the HotSync Manager conduit; called as:

rattail palm

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.RattailCommand(config=None, name=None, stdout=None, stderr=None, subcommands=None)

The primary command for Rattail.

This inherits from wuttjamaican:wuttjamaican.commands.base.Command so see those docs for more info.

Custom apps based on Rattail will probably want to make and register their own Command class derived from this one. Again see upstream docs for more details.

Rattail extends the upstream class by adding the following:

add_args()

Configure args for the main command arg parser.

Rattail extends the upstream add_args() by adding various command line args which have traditionally been available for it. Some of these may disappear some day but no changes are planned just yet.

property db_config_section

Name of section in config file which should have database connection info. This defaults to 'rattail.db' but may be overridden so the command framework can sit in front of a non-Rattail database if needed.

This is used to auto-configure a “default” database engine for the app, when any command is invoked.

property db_model

Returns a reference to configured model module.

This is a compatibility wrapper around rattail.config.RattailConfig.get_model(). New code should use that instead; this may eventually be removed.

property db_session_factory

Returns a reference to the configured session factory.

This is a compatibility wrapper around rattail.app.AppHandler.make_session(). New code should use that instead; this may eventually be removed.

iter_subcommands()

Returns a generator for the subcommands, sorted by name.

This should probably not be used; instead see upstream wuttjamaican:wuttjamaican.commands.base.Command.sorted_subcommands().

make_config(args)

Make the config object in preparation for running a subcommand.

See also upstream make_config() but for now, Rattail overrides this completely, mostly for the sake of versioning setup.

prep_subcommand(subcmd, args)

Rattail overrides this method to apply some of the global args directly to the subcommand object.

See also upstream prep_subcommand().

class rattail.commands.base.RattailSubcommand(*args, **kwargs)

Base class for subcommands.

This inherits from wuttjamaican.commands.base.Subcommand so see those docs for more info.

Rattail extends the subcommand to include:

runas_username

Username (username) corresponding to the User which the command should “run as” - i.e. for sake of version history etc.

show_progress

Boolean indicating whether progress should be shown for the subcommand.

progress

Optional factory to be used when creating progress objects. This is None by default but if show_progress is enabled, then ConsoleProgress is the default factory.

verbose

Flag indicating the subcommand should be free to print arbitrary messages to stdout.

add_args()

This is the “same” as upstream wuttjamaican:wuttjamaican.commands.base.Subcommand.add_args() except Rattail must customize this to also invoke its deprecated method, add_parser_args().

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

finalize_session(session, dry_run=False, success=True)

Wrap up the given session, per the given arguments. This is meant to provide a simple convenience, for commands which must do work within a DB session, but would like to support a “dry run” mode.

get_runas_user(session=None, username=None)

Returns a proper User object which the app should “run as” - which would then be used to assign authorship to certain actions taken, for versioning and batch execution etc.

This will attempt to locate the given user record in the DB, querying as needed.

Parameters:

• session – Optional DB session for the lookup. If not specified, one may be created automatically.

• username – Optional username. If not specified, the subcommand (current instance) may provide a default username via its runas_username attribute, or else config will be checked for a default. If no default username can be found, then no DB lookup will be done and the method simply returns None.

Returns:

The User object, or None.

To define the default user via config, add something like:

[rattail]
runas.default = myuser

class rattail.commands.base.RunAndMail(*args, **kwargs)

Run a command as subprocess, and email the result/output

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

class rattail.commands.base.RunSQL(*args, **kwargs)

Run (first statement of) a SQL script against a database

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

rattail.commands.base.Subcommand

alias of RattailSubcommand

class rattail.commands.base.Upgrade(*args, **kwargs)

Upgrade the local Rattail app

add_parser_args(parser)

This method is deprecated and will eventually be removed; please define add_args() instead.

run(args)

Run the subcommand logic. Subclass should override this.

Parameters:

args – Reference to the argparse.Namespace object, as returned by the subcommand arg parser.

The args should have values for everything setup in add_args(). For example if you added the --foo arg then here in run() you can do:

print("foo value is:", args.foo)

Usually of course this method is invoked by way of command line. But if you need to run it programmatically, you should not try to invoke this method directly. Instead create the Command object and invoke its run() method.

For a command line like bin/poser hello --foo=baz then, you might do this:

from poser.commands import PoserCommand

cmd = PoserCommand()
assert cmd.name == 'poser'
cmd.run('hello', '--foo=baz')

rattail.commands.base.date_argument(string)

Validate and coerce a date argument.

This function is designed be used as the type parameter when calling ArgumentParser.add_argument(), e.g.:

parser = ArgumentParser()
parser.add_argument('--date', type=date_argument)

rattail.commands.base.dict_argument(string)

Coerce the given string to a Python dictionary. The string is assumed to be JSON-encoded; this function merely invokes json.loads() on it.

This function is designed be used as the type parameter when calling ArgumentParser.add_argument(), e.g.:

parser = ArgumentParser()
parser.add_argument('--date', type=dict_argument)

rattail.commands.base.list_argument(string)

Coerce the given string to a list of strings, splitting on whitespace and/or commas.

This function is designed be used as the type parameter when calling ArgumentParser.add_argument(), e.g.:

parser = ArgumentParser()
parser.add_argument('--things', type=list_argument)

rattail.commands.base.main(*args)

The primary entry point for the Rattail command system.