| 1 |
# Copyright 2014-2015 Nathan West |
| 2 |
# |
| 3 |
# This file is part of autocommand. |
| 4 |
# |
| 5 |
# autocommand is free software: you can redistribute it and/or modify |
| 6 |
# it under the terms of the GNU Lesser General Public License as published by |
| 7 |
# the Free Software Foundation, either version 3 of the License, or |
| 8 |
# (at your option) any later version. |
| 9 |
# |
| 10 |
# autocommand is distributed in the hope that it will be useful, |
| 11 |
# but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 |
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 |
# GNU Lesser General Public License for more details. |
| 14 |
# |
| 15 |
# You should have received a copy of the GNU Lesser General Public License |
| 16 |
# along with autocommand. If not, see <http://www.gnu.org/licenses/>. |
| 17 |
|
| 18 |
import sys |
| 19 |
from re import compile as compile_regex |
| 20 |
from inspect import signature, getdoc, Parameter |
| 21 |
from argparse import ArgumentParser |
| 22 |
from contextlib import contextmanager |
| 23 |
from functools import wraps |
| 24 |
from io import IOBase |
| 25 |
from autocommand.errors import AutocommandError |
| 26 |
|
| 27 |
|
| 28 |
_empty = Parameter.empty |
| 29 |
|
| 30 |
|
| 31 |
class AnnotationError(AutocommandError): |
| 32 |
'''Annotation error: annotation must be a string, type, or tuple of both''' |
| 33 |
|
| 34 |
|
| 35 |
class PositionalArgError(AutocommandError): |
| 36 |
''' |
| 37 |
Postional Arg Error: autocommand can't handle postional-only parameters |
| 38 |
''' |
| 39 |
|
| 40 |
|
| 41 |
class KWArgError(AutocommandError): |
| 42 |
'''kwarg Error: autocommand can't handle a **kwargs parameter''' |
| 43 |
|
| 44 |
|
| 45 |
class DocstringError(AutocommandError): |
| 46 |
'''Docstring error''' |
| 47 |
|
| 48 |
|
| 49 |
class TooManySplitsError(DocstringError): |
| 50 |
''' |
| 51 |
The docstring had too many ---- section splits. Currently we only support |
| 52 |
using up to a single split, to split the docstring into description and |
| 53 |
epilog parts. |
| 54 |
''' |
| 55 |
|
| 56 |
|
| 57 |
def _get_type_description(annotation): |
| 58 |
''' |
| 59 |
Given an annotation, return the (type, description) for the parameter. |
| 60 |
If you provide an annotation that is somehow both a string and a callable, |
| 61 |
the behavior is undefined. |
| 62 |
''' |
| 63 |
if annotation is _empty: |
| 64 |
return None, None |
| 65 |
elif callable(annotation): |
| 66 |
return annotation, None |
| 67 |
elif isinstance(annotation, str): |
| 68 |
return None, annotation |
| 69 |
elif isinstance(annotation, tuple): |
| 70 |
try: |
| 71 |
arg1, arg2 = annotation |
| 72 |
except ValueError as e: |
| 73 |
raise AnnotationError(annotation) from e |
| 74 |
else: |
| 75 |
if callable(arg1) and isinstance(arg2, str): |
| 76 |
return arg1, arg2 |
| 77 |
elif isinstance(arg1, str) and callable(arg2): |
| 78 |
return arg2, arg1 |
| 79 |
|
| 80 |
raise AnnotationError(annotation) |
| 81 |
|
| 82 |
|
| 83 |
def _add_arguments(param, parser, used_char_args, add_nos): |
| 84 |
''' |
| 85 |
Add the argument(s) to an ArgumentParser (using add_argument) for a given |
| 86 |
parameter. used_char_args is the set of -short options currently already in |
| 87 |
use, and is updated (if necessary) by this function. If add_nos is True, |
| 88 |
this will also add an inverse switch for all boolean options. For |
| 89 |
instance, for the boolean parameter "verbose", this will create --verbose |
| 90 |
and --no-verbose. |
| 91 |
''' |
| 92 |
|
| 93 |
# Impl note: This function is kept separate from make_parser because it's |
| 94 |
# already very long and I wanted to separate out as much as possible into |
| 95 |
# its own call scope, to prevent even the possibility of suble mutation |
| 96 |
# bugs. |
| 97 |
if param.kind is param.POSITIONAL_ONLY: |
| 98 |
raise PositionalArgError(param) |
| 99 |
elif param.kind is param.VAR_KEYWORD: |
| 100 |
raise KWArgError(param) |
| 101 |
|
| 102 |
# These are the kwargs for the add_argument function. |
| 103 |
arg_spec = {} |
| 104 |
is_option = False |
| 105 |
|
| 106 |
# Get the type and default from the annotation. |
| 107 |
arg_type, description = _get_type_description(param.annotation) |
| 108 |
|
| 109 |
# Get the default value |
| 110 |
default = param.default |
| 111 |
|
| 112 |
# If there is no explicit type, and the default is present and not None, |
| 113 |
# infer the type from the default. |
| 114 |
if arg_type is None and default not in {_empty, None}: |
| 115 |
arg_type = type(default) |
| 116 |
|
| 117 |
# Add default. The presence of a default means this is an option, not an |
| 118 |
# argument. |
| 119 |
if default is not _empty: |
| 120 |
arg_spec['default'] = default |
| 121 |
is_option = True |
| 122 |
|
| 123 |
# Add the type |
| 124 |
if arg_type is not None: |
| 125 |
# Special case for bool: make it just a --switch |
| 126 |
if arg_type is bool: |
| 127 |
if not default or default is _empty: |
| 128 |
arg_spec['action'] = 'store_true' |
| 129 |
else: |
| 130 |
arg_spec['action'] = 'store_false' |
| 131 |
|
| 132 |
# Switches are always options |
| 133 |
is_option = True |
| 134 |
|
| 135 |
# Special case for file types: make it a string type, for filename |
| 136 |
elif isinstance(default, IOBase): |
| 137 |
arg_spec['type'] = str |
| 138 |
|
| 139 |
# TODO: special case for list type. |
| 140 |
# - How to specificy type of list members? |
| 141 |
# - param: [int] |
| 142 |
# - param: int =[] |
| 143 |
# - action='append' vs nargs='*' |
| 144 |
|
| 145 |
else: |
| 146 |
arg_spec['type'] = arg_type |
| 147 |
|
| 148 |
# nargs: if the signature includes *args, collect them as trailing CLI |
| 149 |
# arguments in a list. *args can't have a default value, so it can never be |
| 150 |
# an option. |
| 151 |
if param.kind is param.VAR_POSITIONAL: |
| 152 |
# TODO: consider depluralizing metavar/name here. |
| 153 |
arg_spec['nargs'] = '*' |
| 154 |
|
| 155 |
# Add description. |
| 156 |
if description is not None: |
| 157 |
arg_spec['help'] = description |
| 158 |
|
| 159 |
# Get the --flags |
| 160 |
flags = [] |
| 161 |
name = param.name |
| 162 |
|
| 163 |
if is_option: |
| 164 |
# Add the first letter as a -short option. |
| 165 |
for letter in name[0], name[0].swapcase(): |
| 166 |
if letter not in used_char_args: |
| 167 |
used_char_args.add(letter) |
| 168 |
flags.append('-{}'.format(letter)) |
| 169 |
break |
| 170 |
|
| 171 |
# If the parameter is a --long option, or is a -short option that |
| 172 |
# somehow failed to get a flag, add it. |
| 173 |
if len(name) > 1 or not flags: |
| 174 |
flags.append('--{}'.format(name)) |
| 175 |
|
| 176 |
arg_spec['dest'] = name |
| 177 |
else: |
| 178 |
flags.append(name) |
| 179 |
|
| 180 |
parser.add_argument(*flags, **arg_spec) |
| 181 |
|
| 182 |
# Create the --no- version for boolean switches |
| 183 |
if add_nos and arg_type is bool: |
| 184 |
parser.add_argument( |
| 185 |
'--no-{}'.format(name), |
| 186 |
action='store_const', |
| 187 |
dest=name, |
| 188 |
const=default if default is not _empty else False) |
| 189 |
|
| 190 |
|
| 191 |
def make_parser(func_sig, description, epilog, add_nos): |
| 192 |
''' |
| 193 |
Given the signature of a function, create an ArgumentParser |
| 194 |
''' |
| 195 |
parser = ArgumentParser(description=description, epilog=epilog) |
| 196 |
|
| 197 |
used_char_args = {'h'} |
| 198 |
|
| 199 |
# Arange the params so that single-character arguments are first. This |
| 200 |
# esnures they don't have to get --long versions. sorted is stable, so the |
| 201 |
# parameters will otherwise still be in relative order. |
| 202 |
params = sorted( |
| 203 |
func_sig.parameters.values(), |
| 204 |
key=lambda param: len(param.name) > 1) |
| 205 |
|
| 206 |
for param in params: |
| 207 |
_add_arguments(param, parser, used_char_args, add_nos) |
| 208 |
|
| 209 |
return parser |
| 210 |
|
| 211 |
|
| 212 |
_DOCSTRING_SPLIT = compile_regex(r'\n\s*-{4,}\s*\n') |
| 213 |
|
| 214 |
|
| 215 |
def parse_docstring(docstring): |
| 216 |
''' |
| 217 |
Given a docstring, parse it into a description and epilog part |
| 218 |
''' |
| 219 |
if docstring is None: |
| 220 |
return '', '' |
| 221 |
|
| 222 |
parts = _DOCSTRING_SPLIT.split(docstring) |
| 223 |
|
| 224 |
if len(parts) == 1: |
| 225 |
return docstring, '' |
| 226 |
elif len(parts) == 2: |
| 227 |
return parts[0], parts[1] |
| 228 |
else: |
| 229 |
raise TooManySplitsError() |
| 230 |
|
| 231 |
|
| 232 |
def autoparse( |
| 233 |
func=None, *, |
| 234 |
description=None, |
| 235 |
epilog=None, |
| 236 |
add_nos=False, |
| 237 |
parser=None): |
| 238 |
''' |
| 239 |
This decorator converts a function that takes normal arguments into a |
| 240 |
function which takes a single optional argument, argv, parses it using an |
| 241 |
argparse.ArgumentParser, and calls the underlying function with the parsed |
| 242 |
arguments. If it is not given, sys.argv[1:] is used. This is so that the |
| 243 |
function can be used as a setuptools entry point, as well as a normal main |
| 244 |
function. sys.argv[1:] is not evaluated until the function is called, to |
| 245 |
allow injecting different arguments for testing. |
| 246 |
|
| 247 |
It uses the argument signature of the function to create an |
| 248 |
ArgumentParser. Parameters without defaults become positional parameters, |
| 249 |
while parameters *with* defaults become --options. Use annotations to set |
| 250 |
the type of the parameter. |
| 251 |
|
| 252 |
The `desctiption` and `epilog` parameters corrospond to the same respective |
| 253 |
argparse parameters. If no description is given, it defaults to the |
| 254 |
decorated functions's docstring, if present. |
| 255 |
|
| 256 |
If add_nos is True, every boolean option (that is, every parameter with a |
| 257 |
default of True/False or a type of bool) will have a --no- version created |
| 258 |
as well, which inverts the option. For instance, the --verbose option will |
| 259 |
have a --no-verbose counterpart. These are not mutually exclusive- |
| 260 |
whichever one appears last in the argument list will have precedence. |
| 261 |
|
| 262 |
If a parser is given, it is used instead of one generated from the function |
| 263 |
signature. In this case, no parser is created; instead, the given parser is |
| 264 |
used to parse the argv argument. The parser's results' argument names must |
| 265 |
match up with the parameter names of the decorated function. |
| 266 |
|
| 267 |
The decorated function is attached to the result as the `func` attribute, |
| 268 |
and the parser is attached as the `parser` attribute. |
| 269 |
''' |
| 270 |
|
| 271 |
# If @autoparse(...) is used instead of @autoparse |
| 272 |
if func is None: |
| 273 |
return lambda f: autoparse( |
| 274 |
f, description=description, |
| 275 |
epilog=epilog, |
| 276 |
add_nos=add_nos, |
| 277 |
parser=parser) |
| 278 |
|
| 279 |
func_sig = signature(func) |
| 280 |
|
| 281 |
docstr_description, docstr_epilog = parse_docstring(getdoc(func)) |
| 282 |
|
| 283 |
if parser is None: |
| 284 |
parser = make_parser( |
| 285 |
func_sig, |
| 286 |
description or docstr_description, |
| 287 |
epilog or docstr_epilog, |
| 288 |
add_nos) |
| 289 |
|
| 290 |
@wraps(func) |
| 291 |
def autoparse_wrapper(argv=None): |
| 292 |
if argv is None: |
| 293 |
argv = sys.argv[1:] |
| 294 |
|
| 295 |
# Get empty argument binding, to fill with parsed arguments. This |
| 296 |
# object does all the heavy lifting of turning named arguments into |
| 297 |
# into correctly bound *args and **kwargs. |
| 298 |
parsed_args = func_sig.bind_partial() |
| 299 |
parsed_args.arguments.update(vars(parser.parse_args(argv))) |
| 300 |
|
| 301 |
return func(*parsed_args.args, **parsed_args.kwargs) |
| 302 |
|
| 303 |
# TODO: attach an updated __signature__ to autoparse_wrapper, just in case. |
| 304 |
|
| 305 |
# Attach the wrapped function and parser, and return the wrapper. |
| 306 |
autoparse_wrapper.func = func |
| 307 |
autoparse_wrapper.parser = parser |
| 308 |
return autoparse_wrapper |
| 309 |
|
| 310 |
|
| 311 |
@contextmanager |
| 312 |
def smart_open(filename_or_file, *args, **kwargs): |
| 313 |
''' |
| 314 |
This context manager allows you to open a filename, if you want to default |
| 315 |
some already-existing file object, like sys.stdout, which shouldn't be |
| 316 |
closed at the end of the context. If the filename argument is a str, bytes, |
| 317 |
or int, the file object is created via a call to open with the given *args |
| 318 |
and **kwargs, sent to the context, and closed at the end of the context, |
| 319 |
just like "with open(filename) as f:". If it isn't one of the openable |
| 320 |
types, the object simply sent to the context unchanged, and left unclosed |
| 321 |
at the end of the context. Example: |
| 322 |
|
| 323 |
def work_with_file(name=sys.stdout): |
| 324 |
with smart_open(name) as f: |
| 325 |
# Works correctly if name is a str filename or sys.stdout |
| 326 |
print("Some stuff", file=f) |
| 327 |
# If it was a filename, f is closed at the end here. |
| 328 |
''' |
| 329 |
if isinstance(filename_or_file, (str, bytes, int)): |
| 330 |
with open(filename_or_file, *args, **kwargs) as file: |
| 331 |
yield file |
| 332 |
else: |
| 333 |
yield filename_or_file |