Command Line Interface Support (ligo.skymap.tool)

Functions that support the command line interface.

class ligo.skymap.tool.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True)

Bases: ArgumentParser

An ArgumentParser subclass with some sensible defaults.

• Any .py suffix is stripped from the program name, because the program is probably being invoked from the stub shell script.

• The description is taken from the docstring of the file in which the ArgumentParser is created.

• If the description is taken from the docstring, then whitespace in the description is preserved.

• A --version option is added that prints the version of ligo.skymap.

• The Namespace object returned by parser.parse_args() can be used as a context manager, in a with:: statement, to close all opened files.

class ligo.skymap.tool.DirType(create=False)

Bases: object

Factory for directory arguments.

class ligo.skymap.tool.EnableAction(option_strings, dest, default=True, required=False, help=None)

Bases: Action

class ligo.skymap.tool.FileType(mode='r', bufsize=-1, encoding=None, errors=None)

Bases: FileType

Inherit from argparse.FileType to enable opening stdin or stdout in binary mode.

This is a workaround for https://bugs.python.org/issue14156, which is fixed in Python 3.9.12, 3.10.3, and >=3.11.0.

FIXME: Remove this when we drop support for Python 3.10.

class ligo.skymap.tool.GlobAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: _StoreAction

Generate a list of filenames from a list of filenames and globs.

class ligo.skymap.tool.HelpChoicesAction(option_strings, choices=(), dest='==SUPPRESS==', default='==SUPPRESS==')

Bases: Action

class ligo.skymap.tool.HelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: RawDescriptionHelpFormatter, ArgumentDefaultsHelpFormatter

class ligo.skymap.tool.LogLevelAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: _StoreAction

class ligo.skymap.tool.Namespace(**kwargs)

Bases: Namespace

A Namespace that can be used in a context to close all open files.

class ligo.skymap.tool.SQLiteType(mode)

Bases: FileType

Open an SQLite database, or fail if it does not exist.

Here is an example of trying to open a file that does not exist for reading (mode=’r’). It should raise an exception:

>>> import tempfile
>>> filetype = SQLiteType('r')
>>> filename = tempfile.mktemp()
>>> # Note, simply check or a FileNotFound error in Python 3.
>>> filetype(filename)
Traceback (most recent call last):
  ...
argparse.ArgumentTypeError: ...

If the file already exists, then it’s fine:

>>> import sqlite3
>>> filetype = SQLiteType('r')
>>> with tempfile.NamedTemporaryFile() as f:
...     with sqlite3.connect(f.name) as db:
...         _ = db.execute('create table foo (bar char)')
...     filetype(f.name)
<sqlite3.Connection object at ...>

Here is an example of opening a file for writing (mode=’w’), which should overwrite the file if it exists. Even if the file was not an SQLite database beforehand, this should work:

>>> filetype = SQLiteType('w')
>>> with tempfile.NamedTemporaryFile(mode='w') as f:
...     print('This is definitely not an SQLite file.', file=f)
...     f.flush()
...     with filetype(f.name) as db:
...         db.execute('create table foo (bar char)')
<sqlite3.Cursor object at ...>

Here is an example of opening a file for appending (mode=’a’), which should NOT overwrite the file if it exists. If the file was not an SQLite database beforehand, this should raise an exception.

>>> filetype = SQLiteType('a')
>>> with tempfile.NamedTemporaryFile(mode='w') as f:
...     print('This is definitely not an SQLite file.', file=f)
...     f.flush()
...     with filetype(f.name) as db:
...         db.execute('create table foo (bar char)')
Traceback (most recent call last):
  ...
sqlite3.DatabaseError: ...

And if the database did exist beforehand, then opening for appending (mode=’a’) should not clobber existing tables.

>>> filetype = SQLiteType('a')
>>> with tempfile.NamedTemporaryFile() as f:
...     with sqlite3.connect(f.name) as db:
...         _ = db.execute('create table foo (bar char)')
...     with filetype(f.name) as db:
...         db.execute('select count(*) from foo').fetchone()
(0,)

ligo.skymap.tool.iterlines(file, start_message='Waiting for input on stdin. Type control-D followed by a newline to terminate.', stop_message='Reached end of file. Exiting.')

Iterate over non-emtpy lines in a file.