omero.cli module

Python driver for OMERO

Provides access to various OMERO.blitz server- and client-side utilities, including starting and stopping servers, running analyses, configuration, and more.

Usable via the ./omero script provided with the distribution as well as from python via import omero.cli; omero.cli.argv().

Arguments are taken from (in order of priority): the run method arguments, sys.argv, and finally from standard-in using the cmd.Cmd.cmdloop method.

class cli.BaseControl(ctx=None, dir=omero_ext.path.path.expand.dirname.dirname.dirname.dirname)

Bases: object

Controls get registered with a CLI instance on loadplugins().

To create a new control, subclass BaseControl, implement _configure, and end your module with:

try:
    register("name", MyControl, HELP)
except:
    if __name__ == "__main__":
        cli = CLI()
        cli.register("name", MyControl, HELP)
        cli.invoke(sys.argv[1:])

This module should be put in the omero.plugins package.

All methods which do NOT begin with “_” are assumed to be accessible to CLI users.

add_error(name, rcode, msg)

Register an Error by name both for discovery via the ErrorsControl as well as for raising an exception via raise_error.

error_admin_only(msg='SecurityViolation: Admins only!', code=111, fatal=True)

error_admin_only_privs(restrictions, msg='SecurityViolation: Admin restrictions: ', code=111, fatal=True)

get_errors()

Returns a mapping from name to Error object

get_subcommands()

Return a list of subcommands

raise_error(name, *args)

Call die on the named Error using the arguments to format the message

reset_errors(replacement=None)

class cli.CLI(prog='/home/docs/checkouts/readthedocs.org/user_builds/omero-py/envs/stable/lib/python3.11/site-packages/sphinx/__main__.py')

Bases: Cmd, Context

Command line interface class. Supports various styles of executing the registered plugins. Each plugin is given the chance to update this class by adding methods of the form “do_<plugin name>”.

class PluginsLoaded

Bases: object

Thread-safe class for storing whether or not all the plugins have been loaded

get()

set()

assertRC()

call(args, strict=True, cwd=None)

Calls the string in a subprocess and dies if the return value is not 0

close()

completedefault(*args)

Method called to complete an input line when no command-specific complete_*() method is available.

By default, it returns an empty list.

completenames(text, line, begidx, endidx)

configure_plugins()

Run to instantiate and configure all plugins which were registered via register_only()

conn(args=None)

Returns any active _client object. If one is present but not alive, it will be removed.

If no client is found and arguments are available, will use the current settings to connect.

If required attributes are missing, will delegate to the login command.

FIXME: Currently differing setting sessions on the same CLI instance will misuse a client.

die(rc, text, newline=True)

execute(line, previous_args)

String/list handling as well as EOF and comment handling. Otherwise, parses the arguments as shlexed and runs the function returned by argparse.

exit(args, newline=True)

get_client()

get_config_property_lines(root_path)

Construct a generator providing each line of the configuration property files from OMERO components then from the top level. Trailing whitespace is stripped from each line.

get_event_context()

initData(properties=None)

Uses “omero prefs” to create an Ice.InitializationData().

invoke(line, strict=False, previous_args=None)

Copied from cmd.py

invokeloop()

loadpath(pathobj)

loadplugins()

Finds all plugins and gives them a chance to register themselves with the CLI instance. Here register_only() is used to guarantee the orderedness of the plugins in the parser

onecmd(line, previous_args=None)

Single command logic. Overrides the cmd.Cmd logic by calling execute. Also handles various exception conditions.

parsePropertyFile(data, output)

popen(args, cwd=None, stdout=-1, stderr=-1, **kwargs)

postcmd(stop, line)

Checks interrupt_loop for True and return as much which will end the call to cmdloop. Otherwise use the default postcmd logic (which simply returns stop)

postloop()

Hook method executed once when the cmdloop() method is about to return.

readDefaults()

register(name, Control, help, epilog=None)

register_only(name, Control, help, epilog=None)

This method is added to the globals when exec() is called on each plugin. A Control class should be passed to the register method which will be added to the CLI.

rv

Return value to be returned

set_client(client)

set_event_context(ec)

waitForPlugins()

class cli.CmdControl(ctx=None, dir=omero_ext.path.path.expand.dirname.dirname.dirname.dirname)

Bases: BaseControl

cmd_type()

create_error_report(rsp)

get_error(rsp)

line_to_opts(line, opts)

main_method(args)

print_detailed_report(req, rsp, status)

Extension point for subclasses.

print_report(req, rsp, status, detailed)

response(client, req, loops=8, ms=500, wait=None)

class cli.Context(controls=None, params=None, prog='/home/docs/checkouts/readthedocs.org/user_builds/omero-py/envs/stable/lib/python3.11/site-packages/sphinx/__main__.py')

Bases: object

Simple context used for default logic. The CLI registry which registers the plugins installs itself as a fully functional Context.

The Context class is designed to increase pluggability. Rather than making calls directly on other plugins directly, the pub() method routes messages to other commands. Similarly, out() and err() should be used for printing statements to the user, and die() should be used for exiting fatally.

call(args)

dbg(text, newline=True, level=1)

Passes text to err() if self.isdebug is set

die(rc, args)

err(text, newline=True)

Expects a single string as argument.

exit(args)

get(key, defvalue=None)

input(prompt, hidden=False, required=False)

Reads from standard in. If hidden == True, then uses getpass

out(text, newline=True)

Expects a single string as argument.

parser_init(parser)

popen(args)

post_process()

Runs further processing once all the controls have been added.

pub(args, strict=False)

pythonpath()

Converts the current sys.path to a PYTHONPATH string to be used by plugins which must start a new process.

Note: this was initially created for running during testing when PYTHONPATH is not properly set.

safePrint(text, stream, newline=True)

Prints text to a given string, capturing any exceptions.

set(key, value=True)

sleep(time)

userdir()

Returns a user directory (as path.path) which can be used for storing configuration. The directory is guaranteed to exist and be private (700) after execution.

class cli.DiagnosticsControl(ctx=None, dir=omero_ext.path.path.expand.dirname.dirname.dirname.dirname)

Bases: BaseControl

Superclass (and SPI-interface) for any control commands that would like to provide a “diagnostics” method, like omero admin diagnostics and omero web diagnostics. The top-level diagnostics command then can find each such plugin and iterate over it.

class cli.DirectoryType(*args: Any, **kwargs: Any)

Bases: FileType

Extension of the argparse.FileType to only allow existing directories.

class cli.Error(ctx, rcode, msg)

Bases: object

Wrapper for error messages which can be registered by an BaseControl subclass in its _configure method. Example:

class MyControl(BaseControl):

def _configure(self, parser):

self.add_error(“NAME”, 100, “some message: %s”) …

def __call__(self, *args):

self.raise_error(“NAME”, “my text”)

die(*args)

Call ctx.die passing the return code and the message for this instance

class cli.ExceptionHandler

Bases: object

Location for all logic which maps from server exceptions to specific states. This could likely be moved elsewhere for general client-side usage.

handle_failed_request(rfe)

is_constraint_violation(ve)

class cli.ExistingFile(*args: Any, **kwargs: Any)

Bases: FileType

Extension of the argparse.FileType that requires an existing file.

class cli.ExperimenterArg(arg)

Bases: object

lookup(client)

class cli.ExperimenterGroupArg(arg)

Bases: object

lookup(client)

class cli.GraphArg(cmd_type)

Bases: object

class cli.GraphControl(ctx=None, dir=omero_ext.path.path.expand.dirname.dirname.dirname.dirname)

Bases: CmdControl

as_doall(req_or_doall)

cmd_type()

combine_commands(commands)

Combine several commands into as few as possible. For simple commands a single combined command is possible, for a skiphead it is more complicated. Here skipheads are combined using their startFrom object type.

default_exclude()

Return a list of types to exclude by default.

main_method(args)

print_request_description(request)

class cli.HelpFormatter(*args: Any, **kwargs: Any)

Bases: RawTextHelpFormatter

argparse.HelpFormatter subclass which cleans up our usage, preventing very long lines in subcommands.

class cli.NewFileType(*args: Any, **kwargs: Any)

Bases: FileType

Extension of the argparse.FileType to prevent overwrite existing files.

exception cli.NonZeroReturnCode(rv, *args)

Bases: Exception

class cli.Parser(*args: Any, **kwargs: Any)

Bases: ArgumentParser

Extension of ArgumentParser for simplifying the _configure() code in most Controls

add(sub, func, help=None, **kwargs)

add_group_print_arguments()

add_group_sorting_arguments()

add_limit_arguments()

add_login_arguments()

add_style_argument()

add_user_print_arguments()

add_user_sorting_arguments()

set_args_unsorted()

sub()

class cli.ProxyStringType(default=None)

Bases: object

To make use of the omero.proxy_to_instance method, an instance can be passed to add_argument with a default value: add_argument(…, type=ProxyStringType(“Image”)) which will take either a proxy string of the form: “Image:1” or simply the ID itself: “1”

class cli.ServiceManagerMixin

Bases: object

A mixin that adds a requires_service_manager method.

This method can be called to check for the presence of an environment variable that indicates the plugin is being controlled by an external service manager.

The class must define a property SERVICE_MANAGER_KEY that is used to construct the name of the OMERO property omero.{SERVICE_MANAGER_KEY}.servicemanager.checkenv defining the name of the environment variable.

requires_service_manager(config)

Checks whether OMERO is being managed by a service manager by checking that a specified environment variable is non-empty.

config: An OMERO ConfigXml object

class cli.UserGroupControl(ctx=None, dir=omero_ext.path.path.expand.dirname.dirname.dirname.dirname)

Bases: BaseControl

add_group_arguments(parser, action='')

add_id_name_arguments(parser, objtype='')

add_single_group_argument(parser, action='', required=True)

add_single_user_argument(parser, action='', required=True)

add_user_and_group_arguments(parser, *args, **kwargs)

add_user_arguments(parser, action='')

addownersbyid(admin, group, users)

addusersbyid(admin, group, users)

error_ambiguous_group(id_or_name, msg='Ambiguous group identifier: %s', code=505, fatal=True)

error_ambiguous_user(id_or_name, msg='Ambiguous user identifier: %s', code=515, fatal=True)

error_invalid_group(group, msg='Unknown group: %s', code=503, fatal=True)

error_invalid_groupid(group_id, msg='Not a valid group ID: %s', code=502, fatal=True)

error_invalid_user(user, msg='Unknown user: %s', code=513, fatal=True)

error_invalid_userid(user_id, msg='Not a valid user ID: %s', code=512, fatal=True)

error_no_group_found(msg='No group found', code=504, fatal=True)

error_no_input_group(msg='No input group is specified', code=501, fatal=True)

error_no_input_user(msg='No input user is specified', code=511, fatal=True)

error_no_user_found(msg='No user found', code=514, fatal=True)

find_group(admin, id_or_name, fatal=False)

find_group_by_id(admin, group_id, fatal=False)

find_group_by_name(admin, group_name, fatal=False)

find_user(admin, id_or_name, fatal=False)

find_user_by_id(admin, user_id, fatal=False)

find_user_by_name(admin, user_name, fatal=False)

get_single_user_group(args, iadmin)

get_users_groups(args, iadmin)

getmemberids(group)

getownerids(group)

getuserids(group)

list_groups(a, args, use_context=False)

Retrieve users from the arguments defined in add_user_arguments()

list_users(a, args, use_context=False)

Retrieve users from the arguments defined in add_user_arguments()

output_groups_list(groups, args)

output_users_list(admin, users, args)

removeownersbyid(admin, group, users)

removeusersbyid(admin, group, users)

class cli.WriteOnceNamespace(*args: Any, **kwargs: Any)

Bases: Namespace

Namespace subclass which prevents overwriting any values by accident.

cli.admin_only(*fargs, **fkwargs)

Checks that the current user is an admin and has sufficient privileges, or throws an exception. If no arguments are present or if full_admin is passed and is True, then this method assumes that the user must be a full admin and have all privileges. To disable this behavior, set full_admin to False.

cli.argv(args=['/home/docs/checkouts/readthedocs.org/user_builds/omero-py/envs/stable/lib/python3.11/site-packages/sphinx/__main__.py', '-T', '-b', 'html', '-d', '_build/doctrees', '-D', 'language=en', '.', '/home/docs/checkouts/readthedocs.org/user_builds/omero-py/checkouts/stable/_readthedocs//html'])

Main entry point for the OMERO command-line interface. First loads all plugins by passing them the classes defined here so they can register their methods.

Then the case where arguments are passed on the command line are handled.

Finally, the cli enters a command loop reading from standard in.

cli.cli_login(*args, **kwargs)

args will be appended to [“-q”, “login”] and then passed to onecmd

kwargs:

• keep_alive