Command line — `selkie.pyx.com`

The selkie.com module contains functionality related to command-line processing, as well as system commands.

selkie.pyx.com.file_size(fn): Returns the file size in bytes.

selkie.pyx.com.wget(url)

selkie.pyx.com.more

The function more() calls print on each item in turn, pausing after a pageful of items has been displayed. Hitting return causes another page to be displayed, and hitting ‘q’ then enter causes more() to quit.

One can adjust the pagesize by setting more.pagesize. For example:

>>> from selkie.pyx.com import more
>>> more.pagesize = 4
>>> more(pots())       
1
2
4
8
q

Shell calls

selkie.pyx.com.system(*args, silent=False)

Execute a system command line. Unless silent=True is specified, the output is printed to stdout. The return value is True if the command executes successfully and False if not. Example:

system('ls', '-l')

selkie.pyx.com.backtick(*args): Runs a command line represented as separated words. Returns the printed output, as a string. Signals an error if the call does not succeed.

selkie.pyx.com.run_command(com, *args, value='', silent=False, color=None)

Unless silent=True, prints incrementally. @arg value - ‘’, ‘v’, ‘vo’, ‘o’. Unless ‘v’, signals an error for nonzero status.

Returns (value, output) if ‘vo’.

Returns value if ‘v’.

Returns output if ‘o’.

selkie.pyx.com.strip_escapes(b): Strips out any xterm escape sequences, such as color changes.

Command-line processing

class selkie.pyx.com.Main

Main provides command-line processing for a Python script. To use it, subclass it and define methods whose name begins with com_. For example:

class MyMain (Main):

    def com_foo (self, x, y, t=None): ...
    def com_foo_bar (self, y): ...

To use it:

if __name__ == '__main__':
    main = MyMain()
    main()

When calling the script:

python -m mymodule foo -t=42 hi bye
python -m mymodule foo hi bye
python -m mymodule foo bar bye

In cases of ambiguity, a word is preferentially taken to be a continuation of the command name. The invocations just given translate to the following calls:

main.com_foo('hi', 'bye', t='42')
main.com_foo('hi', 'bye')
main.com_foo_bar('bye')

A help command (invoked by -? or --help) is automatically generated from the method signatures, the documentation string of the class, and the documentation strings of the methods.

__call__(comline)

If comline is omitted, sys.argv is used. The command line should have the form: command flags args. A method must exist whose name is command prefixed with com_. Its positional arguments determine the number and interpretation of the args, and its keyword arguments determine the valid flags. A flag must have the form -fKW=VAL, where KW is a keyword argument and VAL is the value that it receives. =VAL may be omitted, in which case the value is True.

Comline may also have the form -? or --help, in which case a usage message is printed. The usage message is assembled from:

the class documentation string (of the class specializing Main).

the parameter names of the command methods (those whose names begin with com_).

the documentation strings of the command methods.

class selkie.com.Shift

A command-line processor that Main uses internally. Use it in a with-statement:

with Shift() as shift:
    ...

__call__(tgt): Returns the next argument and advances its internal pointer. Tgt is optional. If provided, Shift advances the pointer and returns True if the next argument equals tgt, and does nothing and returns False otherwise.

able(): Returns True just in case __call__() will succeed. (Note that __call__(tgt) always succeeds.)

error(msg): Prints an error message and usage to stderr, then exits.

peek(tgt): Return the next argument without consuming it. Tgt is optional and interpreted as for __call__().

isflag(): Returns True if the next argument begins with -.

flag(): Returns the next argument, if it is a flag. Returns None otherwise.

ifable(): Returns the next argument, if it exists. Returns None otherwise.

rest(): Returns all remaining arguments.

isdone(): Returns true if no arguments remain.

set_usage(msg): Sets the usage message.

print_usage(): Prints out the usage message.

Timeout

class selkie.pyx.com.Timeout

A with Timeout() block can be used to limit the amount of time that some code can run:

with Timeout(2.0):
    value = do_something()

A timer will run for 2.0 seconds, at which point the body code will be interrupted (using a KeyboardInterrupt, equivalent to ctrl-C). If the body code completes before the timer goes off, the timer will be cancelled.

One can use the effects of the body to determine whether it completed successfully (in the example, by looking at value). Alternatively, Timeout takes a second argument, ontimeout, which is a function that will be called if the body is interrupted by the timer.

Timing

One can create a timer:

>>> timer = Timer() 

Every time one calls str() on it, one obtains a printed version of the elapsed time since it was created:

>>> print timer 
0:00:03.316634

The function that Timer uses for printing is separately available as selkie.string.elapsed_time_str().

Progress indicator

To create a progress indicator:

>>> from sys import stdout
>>> from selkie.pyx.com import Progress
>>> progress = Progress(10, file=stdout)

The value n is the total number of “work units” that will be necessary. To cause a progress message to be printed, increment the indicator:

>>> progress += 1 
Progress: 1/10 (10.00%) Time remaining: ...

One may also call Progress() with no arguments, in which case the number of ticks will be reported, with no estimate of time remaining.

Command line — selkie.pyx.com