argparse

Introduction

The argparse subpackage of arandomness contains scripts and actions to expand the utility of Python’s argparse library.

CheckThreads

CheckThreads is an argparse action, as such, it is called as the value of the action argument in argparse. For example:

from arandomness.argparse import CheckThreads
import argparse
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('-t', '--threads',
                    action=CheckThreads,
                    type=int,
                    default=1,
                    help='number of threads to use')
args = parser.parse_args()

When -t is parsed, the value is passed to CheckThreads which then checks that the value is between 1 and the maximum number of threads on the computer as per multiprocessing.cpu_count().

API Documentation

CopyRight

CopyRight is an argparse action that simply takes in text, strips it of leading and trailing whitespace, prints it, and exits the program. Its functionality is analogous to argparse’s version. The action can take in arbitrary text and is only named CopyRight for code readability.

from arandomness.argparse import CopyRight
import argparse
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--copyright',
                    action=CopyRight,
                    copyright_text='This is my copyright',
                    help='print copyright and exit')
args = parser.parse_args()

API Documentation

COpen

# TODO: Add copen to files, move most of this there, and just reference it

COpen is an argparse action that seamlessly handles reading and writing compressed files using the gzip, bz2, and lzma libraries. To do this, COpen actually exposes the arguments of each to libraries *File function to the command line after automatically selecting the proper library based on the arguments it receives. Essentially, this action operates in a read mode and a write/append mode. In read mode, when mode is equal to any read mode supported by the appropriate library such as r or rb, COpen reads the first few bytes of the file to see what compression format the file uses and then opens the file with the corresponding in decompression algorithm. In write mode, basically when mode is set to anything else, COpen just checks the file extension and maps it to the corresponding compression algorithm. If COpen does not recognize the first few bytes of a file or a file extension, it defaults to reading and writing in plain text.

As aforementioned, COpen exposes the arguments of the underlying library. It does this by collecting arbitrary arguments, filtering them by the supported arguments of the *File functions, and only passing those arguments to the function. For example, GzipFile and BZ2File can control the level on compression via the argument compresslevel while LZMAFile uses preset to control compression levels. In order to use these arguments at the argparse level, simply add them as options to COpen as follows:

from arandomness.argparse import COpen
import argparse
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--gzip',
                    action=COpen,
                    mode='r',
                    type=str,
                    compresslevel=9,
                    help='compressed file to read')
parser.add_argument('--bz2',
                    action=COpen,
                    mode='w',
                    type=str,
                    compresslevel=9
                    help='compressed file to write')
parser.add_argument('--lzma',
                    action=COpen,
                    mode='w',
                    type=str,
                    preset=9,
                    help='compressed file to write')
args = parser.parse_args(['-i', 'input.gz', '-o', 'output.xz'])

As stated, this works for any argument and arguments that aren’t supported by the *File are silently ignored.

Common use example:

from arandomness.argparse import COpen
import argparse
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('-i', '--input',
                    action=COpen,
                    mode='r',
                    type=str,
                    help='compressed file to read')
parser.add_argument('-o', '--output',
                    action=COpen,
                    mode='w',
                    type=str,
                    help='compressed file to write')
args = parser.parse_args(['-i', 'input.gz', '-o', 'output.xz'])

API Documentation

ParseSeparator

By default, argparse parses multiple arguments by spaces. While useful, it can sometimes be more practical, or at least easier to read, arguments parsed by commas or some other separator character when multiple arguments make use of nargs. ParseSeparator simply takes a string, splits it by the user-defined separator, and sets the resulting list as the value for the argument. For example:

from arandomness.argparse import ParseSeparator
import argparse
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('-a', '--an_argument',
                    action=ParseSeparator,
                    type=str,
                    sep=',',
                    help='nargs using a string')
args = parser.parse_args(['hello,world'])
print(args.an_argument)

So the argument hello,world would be set as ['hello', 'world'] in args.

API Documentation