pax_global_header00006660000000000000000000000064143357545440014530gustar00rootroot0000000000000052 comment=9d95de8ad227a76604a9205b5b211bc2a0576e91 autocommand-2.2.2/000077500000000000000000000000001433575454400140425ustar00rootroot00000000000000autocommand-2.2.2/.coveragerc000066400000000000000000000000251433575454400161600ustar00rootroot00000000000000[run] branch = True autocommand-2.2.2/.gitignore000066400000000000000000000013111433575454400160260ustar00rootroot00000000000000# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] # C extensions *.so # Distribution / packaging .Python env/ build/ develop-eggs/ dist/ downloads/ eggs/ lib/ lib64/ parts/ sdist/ var/ *.egg-info/ .installed.cfg *.egg # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .coverage .cache nosetests.xml coverage.xml *,cover # Translations *.mo *.pot # Django stuff: *.log # Sphinx documentation docs/_build/ # PyBuilder target/ .env/ *.sublime-workspace *~ autocommand-2.2.2/.travis.yml000066400000000000000000000010241433575454400161500ustar00rootroot00000000000000language: python python: - '3.7' - '3.8' - '3.9' - '3.10' - '3.11' install: - pip install -e . - pip install -r test_requirements.txt script: - sh util/test.sh after_success: - coveralls deploy: provider: pypi user: Lucretiel password: secure: kLTVnrjyggnqaGnLAi5M02LDGIC/hfQmdFD+2onZVjRyj3EKYvZ/INz9NtIPgMo4ocixe59LPJI40nORm53ifPiKZs0HikRw7Z/ebzqDXsyShlP4alxd35jXglDV+dRF8yT86UxlLYaUWp5JYODcGKZuMpBGqxu6KD2apq1EILc= on: tags: true python: '3.11' distributions: sdist bdist_wheel sudo: false autocommand-2.2.2/LICENSE000066400000000000000000000167221433575454400150570ustar00rootroot00000000000000GNU LESSER GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below. 0. Additional Definitions. As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License. "The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below. An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library. A "Combined Work" is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the "Linked Version". The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version. The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work. 1. Exception to Section 3 of the GNU GPL. You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL. 2. Conveying Modified Versions. If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version: a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy. 3. Object Code Incorporating Material from Library Header Files. The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following: a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the object code with a copy of the GNU GPL and this license document. 4. Combined Works. You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following: a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the Combined Work with a copy of the GNU GPL and this license document. c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document. d) Do one of the following: 0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source. 1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version. e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.) 5. Combined Libraries. You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License. b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 6. Revised Versions of the GNU Lesser General Public License. The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation. If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library. autocommand-2.2.2/MANIFEST.in000066400000000000000000000000471433575454400156010ustar00rootroot00000000000000include LICENSE README.rst MANIFEST.in autocommand-2.2.2/README.md000066400000000000000000000333621433575454400153300ustar00rootroot00000000000000[![PyPI version](https://badge.fury.io/py/autocommand.svg)](https://badge.fury.io/py/autocommand) # autocommand A library to automatically generate and run simple argparse parsers from function signatures. ## Installation Autocommand is installed via pip: ``` $ pip install autocommand ``` ## Usage Autocommand turns a function into a command-line program. It converts the function's parameter signature into command-line arguments, and automatically runs the function if the module was called as `__main__`. In effect, it lets your create a smart main function. ```python from autocommand import autocommand # This program takes exactly one argument and echos it. @autocommand(__name__) def echo(thing): print(thing) ``` ``` $ python echo.py hello hello $ python echo.py -h usage: echo [-h] thing positional arguments: thing optional arguments: -h, --help show this help message and exit $ python echo.py hello world # too many arguments usage: echo.py [-h] thing echo.py: error: unrecognized arguments: world ``` As you can see, autocommand converts the signature of the function into an argument spec. When you run the file as a program, autocommand collects the command-line arguments and turns them into function arguments. The function is executed with these arguments, and then the program exits with the return value of the function, via `sys.exit`. Autocommand also automatically creates a usage message, which can be invoked with `-h` or `--help`, and automatically prints an error message when provided with invalid arguments. ### Types You can use a type annotation to give an argument a type. Any type (or in fact any callable) that returns an object when given a string argument can be used, though there are a few special cases that are described later. ```python @autocommand(__name__) def net_client(host, port: int): ... ``` Autocommand will catch `TypeErrors` raised by the type during argument parsing, so you can supply a callable and do some basic argument validation as well. ### Trailing Arguments You can add a `*args` parameter to your function to give it trailing arguments. The command will collect 0 or more trailing arguments and supply them to `args` as a tuple. If a type annotation is supplied, the type is applied to each argument. ```python # Write the contents of each file, one by one @autocommand(__name__) def cat(*files): for filename in files: with open(filename) as file: for line in file: print(line.rstrip()) ``` ``` $ python cat.py -h usage: ipython [-h] [file [file ...]] positional arguments: file optional arguments: -h, --help show this help message and exit ``` ### Options To create `--option` switches, just assign a default. Autocommand will automatically create `--long` and `-s`hort switches. ```python @autocommand(__name__) def do_with_config(argument, config='~/foo.conf'): pass ``` ``` $ python example.py -h usage: example.py [-h] [-c CONFIG] argument positional arguments: argument optional arguments: -h, --help show this help message and exit -c CONFIG, --config CONFIG ``` The option's type is automatically deduced from the default, unless one is explicitly given in an annotation: ```python @autocommand(__name__) def http_connect(host, port=80): print('{}:{}'.format(host, port)) ``` ``` $ python http.py -h usage: http.py [-h] [-p PORT] host positional arguments: host optional arguments: -h, --help show this help message and exit -p PORT, --port PORT $ python http.py localhost localhost:80 $ python http.py localhost -p 8080 localhost:8080 $ python http.py localhost -p blah usage: http.py [-h] [-p PORT] host http.py: error: argument -p/--port: invalid int value: 'blah' ``` #### None If an option is given a default value of `None`, it reads in a value as normal, but supplies `None` if the option isn't provided. #### Switches If an argument is given a default value of `True` or `False`, or given an explicit `bool` type, it becomes an option switch. ```python @autocommand(__name__) def example(verbose=False, quiet=False): pass ``` ``` $ python example.py -h usage: example.py [-h] [-v] [-q] optional arguments: -h, --help show this help message and exit -v, --verbose -q, --quiet ``` Autocommand attempts to do the "correct thing" in these cases- if the default is `True`, then supplying the switch makes the argument `False`; if the type is `bool` and the default is some other `True` value, then supplying the switch makes the argument `False`, while not supplying the switch makes the argument the default value. Autocommand also supports the creation of switch inverters. Pass `add_nos=True` to `autocommand` to enable this. ``` @autocommand(__name__, add_nos=True) def example(verbose=False): pass ``` ``` $ python example.py -h usage: ipython [-h] [-v] [--no-verbose] optional arguments: -h, --help show this help message and exit -v, --verbose --no-verbose ``` Using the `--no-` version of a switch will pass the opposite value in as a function argument. If multiple switches are present, the last one takes precedence. #### Files If the default value is a file object, such as `sys.stdout`, then autocommand just looks for a string, for a file path. It doesn't do any special checking on the string, though (such as checking if the file exists); it's better to let the client decide how to handle errors in this case. Instead, it provides a special context manager called `smart_open`, which behaves exactly like `open` if a filename or other openable type is provided, but also lets you use already open files: ```python from autocommand import autocommand, smart_open import sys # Write the contents of stdin, or a file, to stdout @autocommand(__name__) def write_out(infile=sys.stdin): with smart_open(infile) as f: for line in f: print(line.rstrip()) # If a file was opened, it is closed here. If it was just stdin, it is untouched. ``` ``` $ echo "Hello World!" | python write_out.py | tee hello.txt Hello World! $ python write_out.py --infile hello.txt Hello World! ``` ### Descriptions and docstrings The `autocommand` decorator accepts `description` and `epilog` kwargs, corresponding to the `description `_ and `epilog `_ of the `ArgumentParser`. If no description is given, but the decorated function has a docstring, then it is taken as the `description` for the `ArgumentParser`. You can also provide both the description and epilog in the docstring by splitting it into two sections with 4 or more - characters. ```python @autocommand(__name__) def copy(infile=sys.stdin, outfile=sys.stdout): ''' Copy an the contents of a file (or stdin) to another file (or stdout) ---------- Some extra documentation in the epilog ''' with smart_open(infile) as istr: with smart_open(outfile, 'w') as ostr: for line in istr: ostr.write(line) ``` ``` $ python copy.py -h usage: copy.py [-h] [-i INFILE] [-o OUTFILE] Copy an the contents of a file (or stdin) to another file (or stdout) optional arguments: -h, --help show this help message and exit -i INFILE, --infile INFILE -o OUTFILE, --outfile OUTFILE Some extra documentation in the epilog $ echo "Hello World" | python copy.py --outfile hello.txt $ python copy.py --infile hello.txt --outfile hello2.txt $ python copy.py --infile hello2.txt Hello World ``` ### Parameter descriptions You can also attach description text to individual parameters in the annotation. To attach both a type and a description, supply them both in any order in a tuple ```python @autocommand(__name__) def copy_net( infile: 'The name of the file to send', host: 'The host to send the file to', port: (int, 'The port to connect to')): ''' Copy a file over raw TCP to a remote destination. ''' # Left as an exercise to the reader ``` ### Decorators and wrappers Autocommand automatically follows wrapper chains created by `@functools.wraps`. This means that you can apply other wrapping decorators to your main function, and autocommand will still correctly detect the signature. ```python from functools import wraps from autocommand import autocommand def print_yielded(func): ''' Convert a generator into a function that prints all yielded elements ''' @wraps(func) def wrapper(*args, **kwargs): for thing in func(*args, **kwargs): print(thing) return wrapper @autocommand(__name__, description= 'Print all the values from START to STOP, inclusive, in steps of STEP', epilog= 'STOP and STEP default to 1') @print_yielded def seq(stop, start=1, step=1): for i in range(start, stop + 1, step): yield i ``` ``` $ seq.py -h usage: seq.py [-h] [-s START] [-S STEP] stop Print all the values from START to STOP, inclusive, in steps of STEP positional arguments: stop optional arguments: -h, --help show this help message and exit -s START, --start START -S STEP, --step STEP STOP and STEP default to 1 ``` Even though autocommand is being applied to the `wrapper` returned by `print_yielded`, it still retreives the signature of the underlying `seq` function to create the argument parsing. ### Custom Parser While autocommand's automatic parser generator is a powerful convenience, it doesn't cover all of the different features that argparse provides. If you need these features, you can provide your own parser as a kwarg to `autocommand`: ```python from argparse import ArgumentParser from autocommand import autocommand parser = ArgumentParser() # autocommand can't do optional positonal parameters parser.add_argument('arg', nargs='?') # or mutually exclusive options group = parser.add_mutually_exclusive_group() group.add_argument('-v', '--verbose', action='store_true') group.add_argument('-q', '--quiet', action='store_true') @autocommand(__name__, parser=parser) def main(arg, verbose, quiet): print(arg, verbose, quiet) ``` ``` $ python parser.py -h usage: write_file.py [-h] [-v | -q] [arg] positional arguments: arg optional arguments: -h, --help show this help message and exit -v, --verbose -q, --quiet $ python parser.py None False False $ python parser.py hello hello False False $ python parser.py -v None True False $ python parser.py -q None False True $ python parser.py -vq usage: parser.py [-h] [-v | -q] [arg] parser.py: error: argument -q/--quiet: not allowed with argument -v/--verbose ``` Any parser should work fine, so long as each of the parser's arguments has a corresponding parameter in the decorated main function. The order of parameters doesn't matter, as long as they are all present. Note that when using a custom parser, autocommand doesn't modify the parser or the retrieved arguments. This means that no description/epilog will be added, and the function's type annotations and defaults (if present) will be ignored. ## Testing and Library use The decorated function is only called and exited from if the first argument to `autocommand` is `'__main__'` or `True`. If it is neither of these values, or no argument is given, then a new main function is created by the decorator. This function has the signature `main(argv=None)`, and is intended to be called with arguments as if via `main(sys.argv[1:])`. The function has the attributes `parser` and `main`, which are the generated `ArgumentParser` and the original main function that was decorated. This is to facilitate testing and library use of your main. Calling the function triggers a `parse_args()` with the supplied arguments, and returns the result of the main function. Note that, while it returns instead of calling `sys.exit`, the `parse_args()` function will raise a `SystemExit` in the event of a parsing error or `-h/--help` argument. ```python @autocommand() def test_prog(arg1, arg2: int, quiet=False, verbose=False): if not quiet: print(arg1, arg2) if verbose: print("LOUD NOISES") return 0 print(test_prog(['-v', 'hello', '80'])) ``` ``` $ python test_prog.py hello 80 LOUD NOISES 0 ``` If the function is called with no arguments, `sys.argv[1:]` is used. This is to allow the autocommand function to be used as a setuptools entry point. ## Exceptions and limitations - There are a few possible exceptions that `autocommand` can raise. All of them derive from `autocommand.AutocommandError`. - If an invalid annotation is given (that is, it isn't a `type`, `str`, `(type, str)`, or `(str, type)`, an `AnnotationError` is raised. The `type` may be any callable, as described in the `Types`_ section. - If the function has a `**kwargs` parameter, a `KWargError` is raised. - If, somehow, the function has a positional-only parameter, a `PositionalArgError` is raised. This means that the argument doesn't have a name, which is currently not possible with a plain `def` or `lambda`, though many built-in functions have this kind of parameter. - There are a few argparse features that are not supported by autocommand. - It isn't possible to have an optional positional argument (as opposed to a `--option`). POSIX thinks this is bad form anyway. - It isn't possible to have mutually exclusive arguments or options - It isn't possible to have subcommands or subparsers, though I'm working on a few solutions involving classes or nested function definitions to allow this. ## Development Autocommand cannot be important from the project root; this is to enforce separation of concerns and prevent accidental importing of `setup.py` or tests. To develop, install the project in editable mode: ``` $ python setup.py develop ``` This will create a link to the source files in the deployment directory, so that any source changes are reflected when it is imported. autocommand-2.2.2/autocommand.sublime-project000066400000000000000000000007141433575454400214010ustar00rootroot00000000000000{ "build_systems": [ { "file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)", "name": "Anaconda Python Builder", "selector": "source.python", "shell_cmd": "\"/usr/local/bin/python3\" -u \"$file\"" } ], "folders": [ { "file_exclude_patterns": [ ".coverage" ], "folder_exclude_patterns": [ "dist", "build", ".env", "__pycache__", "*.egg-info" ], "follow_symlinks": true, "path": "." } ] } autocommand-2.2.2/pyproject.toml000066400000000000000000000014551433575454400167630ustar00rootroot00000000000000[project] name = "autocommand" version = "2.2.2" authors = [ { name="Nathan West" }, ] description = "A library to create a command-line program from a function" readme = "README.md" requires-python = ">=3.7" classifiers = [ "Development Status :: 6 - Mature", "Intended Audience :: Developers", "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Topic :: Software Development", "Topic :: Software Development :: Libraries", "Topic :: Software Development :: Libraries :: Python Modules", ] [project.urls] "Homepage" = "https://github.com/Lucretiel/autocommand" "Bug Tracker" = "https://github.com/Lucretiel/autocommand/issues" autocommand-2.2.2/setup.py000066400000000000000000000017371433575454400155640ustar00rootroot00000000000000from setuptools import setup def getfile(filename): with open(filename) as file: return file.read() setup( name='autocommand', version='2.2.2', packages=[ 'autocommand' ], package_dir={'': 'src'}, platforms='any', license='LGPLv3', author='Nathan West', url='https://github.com/Lucretiel/autocommand', description='A library to create a command-line program from a function', long_description=getfile('README.md'), classifiers=[ 'Development Status :: 6 - Mature', 'Intended Audience :: Developers', 'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)', 'Programming Language :: Python', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3 :: Only', 'Topic :: Software Development', 'Topic :: Software Development :: Libraries', 'Topic :: Software Development :: Libraries :: Python Modules', ], ) autocommand-2.2.2/src/000077500000000000000000000000001433575454400146315ustar00rootroot00000000000000autocommand-2.2.2/src/autocommand/000077500000000000000000000000001433575454400171405ustar00rootroot00000000000000autocommand-2.2.2/src/autocommand/__init__.py000066400000000000000000000020151433575454400212470ustar00rootroot00000000000000# Copyright 2014-2016 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . # flake8 flags all these imports as unused, hence the NOQAs everywhere. from .automain import automain # NOQA from .autoparse import autoparse, smart_open # NOQA from .autocommand import autocommand # NOQA try: from .autoasync import autoasync # NOQA except ImportError: # pragma: no cover pass autocommand-2.2.2/src/autocommand/autoasync.py000066400000000000000000000130601433575454400215200ustar00rootroot00000000000000# Copyright 2014-2015 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . from asyncio import get_event_loop, iscoroutine from functools import wraps from inspect import signature async def _run_forever_coro(coro, args, kwargs, loop): ''' This helper function launches an async main function that was tagged with forever=True. There are two possibilities: - The function is a normal function, which handles initializing the event loop, which is then run forever - The function is a coroutine, which needs to be scheduled in the event loop, which is then run forever - There is also the possibility that the function is a normal function wrapping a coroutine function The function is therefore called unconditionally and scheduled in the event loop if the return value is a coroutine object. The reason this is a separate function is to make absolutely sure that all the objects created are garbage collected after all is said and done; we do this to ensure that any exceptions raised in the tasks are collected ASAP. ''' # Personal note: I consider this an antipattern, as it relies on the use of # unowned resources. The setup function dumps some stuff into the event # loop where it just whirls in the ether without a well defined owner or # lifetime. For this reason, there's a good chance I'll remove the # forever=True feature from autoasync at some point in the future. thing = coro(*args, **kwargs) if iscoroutine(thing): await thing def autoasync(coro=None, *, loop=None, forever=False, pass_loop=False): ''' Convert an asyncio coroutine into a function which, when called, is evaluted in an event loop, and the return value returned. This is intented to make it easy to write entry points into asyncio coroutines, which otherwise need to be explictly evaluted with an event loop's run_until_complete. If `loop` is given, it is used as the event loop to run the coro in. If it is None (the default), the loop is retreived using asyncio.get_event_loop. This call is defered until the decorated function is called, so that callers can install custom event loops or event loop policies after @autoasync is applied. If `forever` is True, the loop is run forever after the decorated coroutine is finished. Use this for servers created with asyncio.start_server and the like. If `pass_loop` is True, the event loop object is passed into the coroutine as the `loop` kwarg when the wrapper function is called. In this case, the wrapper function's __signature__ is updated to remove this parameter, so that autoparse can still be used on it without generating a parameter for `loop`. This coroutine can be called with ( @autoasync(...) ) or without ( @autoasync ) arguments. Examples: @autoasync def get_file(host, port): reader, writer = yield from asyncio.open_connection(host, port) data = reader.read() sys.stdout.write(data.decode()) get_file(host, port) @autoasync(forever=True, pass_loop=True) def server(host, port, loop): yield_from loop.create_server(Proto, host, port) server('localhost', 8899) ''' if coro is None: return lambda c: autoasync( c, loop=loop, forever=forever, pass_loop=pass_loop) # The old and new signatures are required to correctly bind the loop # parameter in 100% of cases, even if it's a positional parameter. # NOTE: A future release will probably require the loop parameter to be # a kwonly parameter. if pass_loop: old_sig = signature(coro) new_sig = old_sig.replace(parameters=( param for name, param in old_sig.parameters.items() if name != "loop")) @wraps(coro) def autoasync_wrapper(*args, **kwargs): # Defer the call to get_event_loop so that, if a custom policy is # installed after the autoasync decorator, it is respected at call time local_loop = get_event_loop() if loop is None else loop # Inject the 'loop' argument. We have to use this signature binding to # ensure it's injected in the correct place (positional, keyword, etc) if pass_loop: bound_args = old_sig.bind_partial() bound_args.arguments.update( loop=local_loop, **new_sig.bind(*args, **kwargs).arguments) args, kwargs = bound_args.args, bound_args.kwargs if forever: local_loop.create_task(_run_forever_coro( coro, args, kwargs, local_loop )) local_loop.run_forever() else: return local_loop.run_until_complete(coro(*args, **kwargs)) # Attach the updated signature. This allows 'pass_loop' to be used with # autoparse if pass_loop: autoasync_wrapper.__signature__ = new_sig return autoasync_wrapper autocommand-2.2.2/src/autocommand/autocommand.py000066400000000000000000000047111433575454400220240ustar00rootroot00000000000000# Copyright 2014-2015 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . from .autoparse import autoparse from .automain import automain try: from .autoasync import autoasync except ImportError: # pragma: no cover pass def autocommand( module, *, description=None, epilog=None, add_nos=False, parser=None, loop=None, forever=False, pass_loop=False): if callable(module): raise TypeError('autocommand requires a module name argument') def autocommand_decorator(func): # Step 1: if requested, run it all in an asyncio event loop. autoasync # patches the __signature__ of the decorated function, so that in the # event that pass_loop is True, the `loop` parameter of the original # function will *not* be interpreted as a command-line argument by # autoparse if loop is not None or forever or pass_loop: func = autoasync( func, loop=None if loop is True else loop, pass_loop=pass_loop, forever=forever) # Step 2: create parser. We do this second so that the arguments are # parsed and passed *before* entering the asyncio event loop, if it # exists. This simplifies the stack trace and ensures errors are # reported earlier. It also ensures that errors raised during parsing & # passing are still raised if `forever` is True. func = autoparse( func, description=description, epilog=epilog, add_nos=add_nos, parser=parser) # Step 3: call the function automatically if __name__ == '__main__' (or # if True was provided) func = automain(module)(func) return func return autocommand_decorator autocommand-2.2.2/src/autocommand/automain.py000066400000000000000000000040341433575454400213300ustar00rootroot00000000000000# Copyright 2014-2015 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . import sys from .errors import AutocommandError class AutomainRequiresModuleError(AutocommandError, TypeError): pass def automain(module, *, args=(), kwargs=None): ''' This decorator automatically invokes a function if the module is being run as the "__main__" module. Optionally, provide args or kwargs with which to call the function. If `module` is "__main__", the function is called, and the program is `sys.exit`ed with the return value. You can also pass `True` to cause the function to be called unconditionally. If the function is not called, it is returned unchanged by the decorator. Usage: @automain(__name__) # Pass __name__ to check __name__=="__main__" def main(): ... If __name__ is "__main__" here, the main function is called, and then sys.exit called with the return value. ''' # Check that @automain(...) was called, rather than @automain if callable(module): raise AutomainRequiresModuleError(module) if module == '__main__' or module is True: if kwargs is None: kwargs = {} # Use a function definition instead of a lambda for a neater traceback def automain_decorator(main): sys.exit(main(*args, **kwargs)) return automain_decorator else: return lambda main: main autocommand-2.2.2/src/autocommand/autoparse.py000066400000000000000000000265721433575454400215310ustar00rootroot00000000000000# Copyright 2014-2015 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . import sys from re import compile as compile_regex from inspect import signature, getdoc, Parameter from argparse import ArgumentParser from contextlib import contextmanager from functools import wraps from io import IOBase from autocommand.errors import AutocommandError _empty = Parameter.empty class AnnotationError(AutocommandError): '''Annotation error: annotation must be a string, type, or tuple of both''' class PositionalArgError(AutocommandError): ''' Postional Arg Error: autocommand can't handle postional-only parameters ''' class KWArgError(AutocommandError): '''kwarg Error: autocommand can't handle a **kwargs parameter''' class DocstringError(AutocommandError): '''Docstring error''' class TooManySplitsError(DocstringError): ''' The docstring had too many ---- section splits. Currently we only support using up to a single split, to split the docstring into description and epilog parts. ''' def _get_type_description(annotation): ''' Given an annotation, return the (type, description) for the parameter. If you provide an annotation that is somehow both a string and a callable, the behavior is undefined. ''' if annotation is _empty: return None, None elif callable(annotation): return annotation, None elif isinstance(annotation, str): return None, annotation elif isinstance(annotation, tuple): try: arg1, arg2 = annotation except ValueError as e: raise AnnotationError(annotation) from e else: if callable(arg1) and isinstance(arg2, str): return arg1, arg2 elif isinstance(arg1, str) and callable(arg2): return arg2, arg1 raise AnnotationError(annotation) def _add_arguments(param, parser, used_char_args, add_nos): ''' Add the argument(s) to an ArgumentParser (using add_argument) for a given parameter. used_char_args is the set of -short options currently already in use, and is updated (if necessary) by this function. If add_nos is True, this will also add an inverse switch for all boolean options. For instance, for the boolean parameter "verbose", this will create --verbose and --no-verbose. ''' # Impl note: This function is kept separate from make_parser because it's # already very long and I wanted to separate out as much as possible into # its own call scope, to prevent even the possibility of suble mutation # bugs. if param.kind is param.POSITIONAL_ONLY: raise PositionalArgError(param) elif param.kind is param.VAR_KEYWORD: raise KWArgError(param) # These are the kwargs for the add_argument function. arg_spec = {} is_option = False # Get the type and default from the annotation. arg_type, description = _get_type_description(param.annotation) # Get the default value default = param.default # If there is no explicit type, and the default is present and not None, # infer the type from the default. if arg_type is None and default not in {_empty, None}: arg_type = type(default) # Add default. The presence of a default means this is an option, not an # argument. if default is not _empty: arg_spec['default'] = default is_option = True # Add the type if arg_type is not None: # Special case for bool: make it just a --switch if arg_type is bool: if not default or default is _empty: arg_spec['action'] = 'store_true' else: arg_spec['action'] = 'store_false' # Switches are always options is_option = True # Special case for file types: make it a string type, for filename elif isinstance(default, IOBase): arg_spec['type'] = str # TODO: special case for list type. # - How to specificy type of list members? # - param: [int] # - param: int =[] # - action='append' vs nargs='*' else: arg_spec['type'] = arg_type # nargs: if the signature includes *args, collect them as trailing CLI # arguments in a list. *args can't have a default value, so it can never be # an option. if param.kind is param.VAR_POSITIONAL: # TODO: consider depluralizing metavar/name here. arg_spec['nargs'] = '*' # Add description. if description is not None: arg_spec['help'] = description # Get the --flags flags = [] name = param.name if is_option: # Add the first letter as a -short option. for letter in name[0], name[0].swapcase(): if letter not in used_char_args: used_char_args.add(letter) flags.append('-{}'.format(letter)) break # If the parameter is a --long option, or is a -short option that # somehow failed to get a flag, add it. if len(name) > 1 or not flags: flags.append('--{}'.format(name)) arg_spec['dest'] = name else: flags.append(name) parser.add_argument(*flags, **arg_spec) # Create the --no- version for boolean switches if add_nos and arg_type is bool: parser.add_argument( '--no-{}'.format(name), action='store_const', dest=name, const=default if default is not _empty else False) def make_parser(func_sig, description, epilog, add_nos): ''' Given the signature of a function, create an ArgumentParser ''' parser = ArgumentParser(description=description, epilog=epilog) used_char_args = {'h'} # Arange the params so that single-character arguments are first. This # esnures they don't have to get --long versions. sorted is stable, so the # parameters will otherwise still be in relative order. params = sorted( func_sig.parameters.values(), key=lambda param: len(param.name) > 1) for param in params: _add_arguments(param, parser, used_char_args, add_nos) return parser _DOCSTRING_SPLIT = compile_regex(r'\n\s*-{4,}\s*\n') def parse_docstring(docstring): ''' Given a docstring, parse it into a description and epilog part ''' if docstring is None: return '', '' parts = _DOCSTRING_SPLIT.split(docstring) if len(parts) == 1: return docstring, '' elif len(parts) == 2: return parts[0], parts[1] else: raise TooManySplitsError() def autoparse( func=None, *, description=None, epilog=None, add_nos=False, parser=None): ''' This decorator converts a function that takes normal arguments into a function which takes a single optional argument, argv, parses it using an argparse.ArgumentParser, and calls the underlying function with the parsed arguments. If it is not given, sys.argv[1:] is used. This is so that the function can be used as a setuptools entry point, as well as a normal main function. sys.argv[1:] is not evaluated until the function is called, to allow injecting different arguments for testing. It uses the argument signature of the function to create an ArgumentParser. Parameters without defaults become positional parameters, while parameters *with* defaults become --options. Use annotations to set the type of the parameter. The `desctiption` and `epilog` parameters corrospond to the same respective argparse parameters. If no description is given, it defaults to the decorated functions's docstring, if present. If add_nos is True, every boolean option (that is, every parameter with a default of True/False or a type of bool) will have a --no- version created as well, which inverts the option. For instance, the --verbose option will have a --no-verbose counterpart. These are not mutually exclusive- whichever one appears last in the argument list will have precedence. If a parser is given, it is used instead of one generated from the function signature. In this case, no parser is created; instead, the given parser is used to parse the argv argument. The parser's results' argument names must match up with the parameter names of the decorated function. The decorated function is attached to the result as the `func` attribute, and the parser is attached as the `parser` attribute. ''' # If @autoparse(...) is used instead of @autoparse if func is None: return lambda f: autoparse( f, description=description, epilog=epilog, add_nos=add_nos, parser=parser) func_sig = signature(func) docstr_description, docstr_epilog = parse_docstring(getdoc(func)) if parser is None: parser = make_parser( func_sig, description or docstr_description, epilog or docstr_epilog, add_nos) @wraps(func) def autoparse_wrapper(argv=None): if argv is None: argv = sys.argv[1:] # Get empty argument binding, to fill with parsed arguments. This # object does all the heavy lifting of turning named arguments into # into correctly bound *args and **kwargs. parsed_args = func_sig.bind_partial() parsed_args.arguments.update(vars(parser.parse_args(argv))) return func(*parsed_args.args, **parsed_args.kwargs) # TODO: attach an updated __signature__ to autoparse_wrapper, just in case. # Attach the wrapped function and parser, and return the wrapper. autoparse_wrapper.func = func autoparse_wrapper.parser = parser return autoparse_wrapper @contextmanager def smart_open(filename_or_file, *args, **kwargs): ''' This context manager allows you to open a filename, if you want to default some already-existing file object, like sys.stdout, which shouldn't be closed at the end of the context. If the filename argument is a str, bytes, or int, the file object is created via a call to open with the given *args and **kwargs, sent to the context, and closed at the end of the context, just like "with open(filename) as f:". If it isn't one of the openable types, the object simply sent to the context unchanged, and left unclosed at the end of the context. Example: def work_with_file(name=sys.stdout): with smart_open(name) as f: # Works correctly if name is a str filename or sys.stdout print("Some stuff", file=f) # If it was a filename, f is closed at the end here. ''' if isinstance(filename_or_file, (str, bytes, int)): with open(filename_or_file, *args, **kwargs) as file: yield file else: yield filename_or_file autocommand-2.2.2/src/autocommand/errors.py000066400000000000000000000015661433575454400210360ustar00rootroot00000000000000# Copyright 2014-2016 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . class AutocommandError(Exception): '''Base class for autocommand exceptions''' pass # Individual modules will define errors specific to that module. autocommand-2.2.2/test/000077500000000000000000000000001433575454400150215ustar00rootroot00000000000000autocommand-2.2.2/test/test_autoasync.py000066400000000000000000000130701433575454400204410ustar00rootroot00000000000000# Copyright 2014-2016 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . import pytest from contextlib import closing, contextmanager asyncio = pytest.importorskip('asyncio') autoasync = pytest.importorskip('autocommand.autoasync').autoasync class YieldOnce: def __await__(self): yield @contextmanager def temporary_context_loop(loop): ''' Set the given loop as the context loop (that is, the loop returned by asyncio.get_event_loop() for the duration of the context) ''' old_loop = asyncio.get_event_loop() asyncio.set_event_loop(loop) try: yield loop finally: asyncio.set_event_loop(old_loop) @pytest.fixture def new_loop(): ''' Get a new event loop. The loop is closed afterwards ''' with closing(asyncio.new_event_loop()) as loop: yield loop @pytest.fixture def context_loop(): ''' Create a new event loop and set it as the current context event loop. asyncio.get_event_loop() will return this loop within this fixture. Restore the original current event loop afterwards. The new loop is also closed afterwards. ''' # Can't reuse new_loop() because some tests require new_loop and # context_loop to be different with closing(asyncio.new_event_loop()) as new_loop: with temporary_context_loop(new_loop): yield new_loop def test_basic_autoasync(context_loop): data = set() async def coro_1(): data.add(1) await YieldOnce() data.add(2) return 1 async def coro_2(): data.add(3) await YieldOnce() data.add(4) return 2 @autoasync async def async_main(): task1 = asyncio.create_task(coro_1()) task2 = asyncio.create_task(coro_2()) result1 = await task1 result2 = await task2 assert result1 == 1 assert result2 == 2 return 3 assert async_main() == 3 assert data == {1, 2, 3, 4} def test_custom_loop(context_loop, new_loop): did_bad_coro_run = False async def bad_coro(): nonlocal did_bad_coro_run did_bad_coro_run = True await YieldOnce() # TODO: this fires a "task wasn't awaited" warning; figure out how to # supress context_loop.create_task(bad_coro()) @autoasync(loop=new_loop) async def async_main(): await YieldOnce() await YieldOnce() return 3 assert async_main() == 3 assert did_bad_coro_run is False def test_pass_loop(context_loop): @autoasync(pass_loop=True) async def async_main(loop): return loop assert async_main() is asyncio.get_event_loop() def test_pass_loop_prior_argument(context_loop): ''' Test that, if loop is the first positional argument, other arguments are still passed correctly ''' @autoasync(pass_loop=True) async def async_main(loop, argument): return loop, argument loop, value = async_main(10) assert loop is asyncio.get_event_loop() assert value == 10 def test_pass_loop_kwarg_only(context_loop): @autoasync(pass_loop=True) async def async_main(*, loop, argument): await YieldOnce() return loop, argument loop, value = async_main(argument=10) assert loop is asyncio.get_event_loop() assert value == 10 def test_run_forever(context_loop): async def stop_loop_after(t): await asyncio.sleep(t) context_loop.stop() retrieved_value = False async def set_value_after(t): nonlocal retrieved_value await asyncio.sleep(t) retrieved_value = True @autoasync(forever=True) async def async_main(): asyncio.create_task(set_value_after(0.1)) asyncio.create_task(stop_loop_after(0.2)) await YieldOnce() async_main() assert retrieved_value def test_run_forever_func(context_loop): async def stop_loop_after(t): await asyncio.sleep(t) context_loop.stop() retrieved_value = False async def set_value_after(t): nonlocal retrieved_value await asyncio.sleep(t) retrieved_value = True @autoasync(forever=True) def main_func(): asyncio.create_task(set_value_after(0.1)) asyncio.create_task(stop_loop_after(0.2)) main_func() assert retrieved_value def test_defered_loop(context_loop, new_loop): ''' Test that, if a new event loop is installed with set_event_loop AFTER the autoasync decorator is applied (and no loop= is explicitly given to autoasync), the new event loop is used when the decorated function is called. ''' @autoasync(pass_loop=True) async def async_main(loop): await YieldOnce() return loop with temporary_context_loop(new_loop): passed_loop = async_main() assert passed_loop is new_loop assert passed_loop is asyncio.get_event_loop() assert passed_loop is not context_loop assert passed_loop is not asyncio.get_event_loop() autocommand-2.2.2/test/test_autocommand.py000066400000000000000000000107741433575454400207520ustar00rootroot00000000000000# Copyright 2014-2016 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . import pytest import sys from unittest.mock import patch, sentinel from autocommand import autocommand autocommand_module = sys.modules['autocommand.autocommand'] def _asyncio_unavailable(): try: import asyncio # This is here to silence flake8 complaining about "unused import" assert asyncio except ImportError: return True else: return False skip_if_async_unavailable = pytest.mark.skipif( _asyncio_unavailable(), reason="async tests require asyncio (python3.4+)") @pytest.fixture def patched_autoparse(): with patch.object( autocommand_module, 'autoparse', autospec=True) as autoparse: yield autoparse @pytest.fixture def patched_autoasync(): with patch.object( autocommand_module, 'autoasync', create=True) as autoasync: if sys.version_info < (3, 4): autoasync.side_effect = NameError('autoasync') yield autoasync @pytest.fixture def patched_automain(): with patch.object( autocommand_module, 'automain', autospec=True) as automain: yield automain def test_autocommand_no_async( patched_automain, patched_autoasync, patched_autoparse): autocommand_wrapped = autocommand( sentinel.module, description=sentinel.description, epilog=sentinel.epilog, add_nos=sentinel.add_nos, parser=sentinel.parser)(sentinel.original_function) assert not patched_autoasync.called patched_autoparse.assert_called_once_with( sentinel.original_function, description=sentinel.description, epilog=sentinel.epilog, add_nos=sentinel.add_nos, parser=sentinel.parser) autoparse_wrapped = patched_autoparse.return_value patched_automain.assert_called_once_with(sentinel.module) patched_automain.return_value.assert_called_once_with(autoparse_wrapped) automain_wrapped = patched_automain.return_value.return_value assert automain_wrapped is autocommand_wrapped @pytest.mark.parametrize( 'input_loop, output_loop', [(sentinel.loop, sentinel.loop), (True, None)]) @skip_if_async_unavailable def test_autocommand_with_async( patched_automain, patched_autoasync, patched_autoparse, input_loop, output_loop): autocommand_wrapped = autocommand( sentinel.module, description=sentinel.description, epilog=sentinel.epilog, add_nos=sentinel.add_nos, parser=sentinel.parser, loop=input_loop, forever=sentinel.forever, pass_loop=sentinel.pass_loop)(sentinel.original_function) patched_autoasync.assert_called_once_with( sentinel.original_function, loop=output_loop, forever=sentinel.forever, pass_loop=sentinel.pass_loop) autoasync_wrapped = patched_autoasync.return_value patched_autoparse.assert_called_once_with( autoasync_wrapped, description=sentinel.description, epilog=sentinel.epilog, add_nos=sentinel.add_nos, parser=sentinel.parser) autoparse_wrapped = patched_autoparse.return_value patched_automain.assert_called_once_with(sentinel.module) patched_automain.return_value.assert_called_once_with(autoparse_wrapped) automain_wrapped = patched_automain.return_value.return_value assert automain_wrapped is autocommand_wrapped def test_autocommand_incorrect_invocation_no_parenthesis( patched_automain, patched_autoparse, patched_autoasync): ''' Test that an exception is raised if the autocommand decorator is called without parenthesis by accident ''' with pytest.raises(TypeError): @autocommand def original_function(): pass autocommand-2.2.2/test/test_automain.py000066400000000000000000000035621433575454400202550ustar00rootroot00000000000000# Copyright 2014-2016 Nathan West # # This file is part of autocommand. # # autocommand is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # autocommand is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with autocommand. If not, see . import pytest from autocommand.automain import automain, AutomainRequiresModuleError @pytest.mark.parametrize('module_name', ['__main__', True]) def test_name_equals_main_or_true(module_name): with pytest.raises(SystemExit): @automain(module_name) def main(): return 0 def test_name_not_main_or_true(): def main(): return 0 wrapped_main = automain('some_module')(main) assert wrapped_main is main def test_invalid_usage(): with pytest.raises(AutomainRequiresModuleError): @automain def main(): return 0 def test_args(): main_called = False with pytest.raises(SystemExit): @automain(True, args=[1, 2]) def main(a, b): nonlocal main_called main_called = True assert a == 1 assert b == 2 assert main_called def test_args_and_kwargs(): main_called = False with pytest.raises(SystemExit): @automain(True, args=[1], kwargs={'b': 2}) def main(a, b): nonlocal main_called main_called = True assert a == 1 assert b == 2 assert main_called autocommand-2.2.2/test/test_autoparse/000077500000000000000000000000001433575454400200635ustar00rootroot00000000000000autocommand-2.2.2/test/test_autoparse/README.md000066400000000000000000000013341433575454400213430ustar00rootroot00000000000000`test_autoparse` ================ It turns out that autoparse is somewhat difficult to purely unit test, because a lot of the functionality is orthogonal (typing, type deduction, argument-vs-option, flag letter assignment), but the orthogonal parts are difficult to isolate implementation and API-wise. Therefore, rather than unit-test each component with mocking so on, even though we test each orthogonal unit of functionality more or less in separate files, we understand that something failing in, say, flag letter assignment could cause a failure in type deduction tests. In the grand scheme of things, autoparse really isn't that complicated, so hopefully a cascading test failure can be easily tracked down no matter what. autocommand-2.2.2/test/test_autoparse/conftest.py000066400000000000000000000056571433575454400222770ustar00rootroot00000000000000from inspect import signature import pytest from autocommand.autoparse import make_parser # TODO: This doesn't really need to be a fixture; replace it with a normal # helper @pytest.fixture(scope='session') def check_parse(): def check_parse_impl(function, *args, add_nos=False, **kwargs): ''' Helper for generalized parser testing. This function takes a function, a set of positional arguments, and a set of keyword argumnets. It creates an argparse parser using `autocommand.autoparse:make_parser` on the signature of the provided function. It then parses the positional arguments using this parser, and asserts that the returned set of parsed arguments matches the given keyword arguments exactly. Arguments: - function: The function to generate a parser for - *args: The set of positional arguments to pass to the generated parser - add_nos: If True, "-no-" versions of the option flags will be created, as per the `autoparse` docs. - **kwargs: The set of parsed argument values to check for. ''' parser = make_parser( func_sig=signature(function), description=None, epilog=None, add_nos=add_nos) parsed_args = vars(parser.parse_args(args)) assert parsed_args == kwargs return check_parse_impl @pytest.fixture def check_help_text(capsys): def check_help_text_impl(func, *texts, reject=()): ''' This helper checks that some set of text is written to stdout or stderr after the called function raises a SystemExit. It is used to test that the underlying ArgumentParser was correctly configured to output a given set of help text(s). func: This should be a wrapped autoparse function that causes a SystemExit exception to be raised (most commonly a function with the -h flag, or with an invalid set of positional arguments). This Exception should be accompanied by some kind of printout from argparse to stderr or stdout. *texts: A set of strings to test for. All of the provided strings will be checked for in the captured stdout/stderr using a standard substring search. reject: A string or set of strings to check do NOT exist anywhere in the output. Currently used as a cludge to test the docstring split behavior. ''' with pytest.raises(SystemExit): func() out, err = capsys.readouterr() # TODO: be wary of argparse's text formatting # TODO: test that the text appears in the order given for text in texts: assert text in out or text in err if isinstance(reject, str): reject = [reject] for text in reject: assert text not in out and text not in err return check_help_text_impl autocommand-2.2.2/test/test_autoparse/test_annotations.py000066400000000000000000000030141433575454400240270ustar00rootroot00000000000000import pytest from autocommand.autoparse import AnnotationError @pytest.mark.parametrize("type_object", [ int, lambda value: "FACTORY({})".format(value) ]) def test_all_annotation_types(check_parse, check_help_text, type_object): # type_object is either `int` or a factory function that converts "str" to # "FACTORY(str)" def func( typed_arg: type_object, note_arg: "note_arg description", note_type: ("note_type description", type_object), type_note: (type_object, "type_note description")): pass check_help_text( lambda: check_parse(func, '-h'), "note_arg description", "note_type description", "type_note description") check_parse( func, "1", "2", "3", "4", typed_arg=type_object("1"), note_arg="2", note_type=type_object("3"), type_note=type_object("4")) @pytest.mark.parametrize('bad_annotation', [ 1000, # An int? What? {'foo': 'bar'}, # A dict isn't any better [int, 'fooo'], # For implementation ease we do ask for a tuple (), # Though the tuple should have things in it (int,), # More things (int, 'hello', 'world'), # TOO MANY THINGS (int, int), # The wrong kinds of things ("hello", "world"), # Nope this is bad too (lambda value: value, lambda value: value), # Too many lambdas ]) def test_bad_annotation(bad_annotation, check_parse): def func(arg: bad_annotation): pass with pytest.raises(AnnotationError): check_parse(func) autocommand-2.2.2/test/test_autoparse/test_bad_signature.py000066400000000000000000000011421433575454400243010ustar00rootroot00000000000000from inspect import signature, Signature, Parameter import pytest from autocommand.autoparse import KWArgError, PositionalArgError, make_parser def test_kwargs(check_parse): def func(**kwargs): pass with pytest.raises(KWArgError): make_parser(signature(func), "", "", False) def test_positional(check_parse): # We have to fake this one, because it isn't possible to create a # positional-only parameter in pure python with pytest.raises(PositionalArgError): make_parser( Signature([Parameter('arg', Parameter.POSITIONAL_ONLY)]), "", "", False) autocommand-2.2.2/test/test_autoparse/test_basic_autoparse.py000066400000000000000000000016031433575454400246400ustar00rootroot00000000000000import pytest def test_basic_positional(check_parse): def func(arg): pass check_parse( func, "foo", arg="foo") @pytest.mark.parametrize('cli_args', [ [], ['value'], ['value1', 'value2'] ]) def test_variadic_positional(check_parse, cli_args): check_parse( lambda arg1, *args: None, 'arg1_value', *cli_args, arg1='arg1_value', args=cli_args) def test_optional_default(check_parse): check_parse( lambda arg="default_value": None, arg="default_value") @pytest.mark.parametrize('flags, result', [ ([], False), (['-f'], True), (['--no-flag'], False), (['--no-flag', '-f'], True), (['--flag', '--no-flag'], False) ]) def test_add_nos(check_parse, flags, result): def func(flag: bool): pass check_parse( func, *flags, add_nos=True, flag=result) autocommand-2.2.2/test/test_autoparse/test_invocation.py000066400000000000000000000054571433575454400236600ustar00rootroot00000000000000from unittest.mock import patch from argparse import ArgumentParser import pytest from autocommand.autoparse import autoparse, TooManySplitsError def test_basic_invocation(): @autoparse def func(arg1, arg2: int, opt1=None, opt2=2, opt3='default', flag=False): return arg1, arg2, opt1, opt2, opt3, flag arg1, arg2, opt1, opt2, opt3, flag = func( ['value1', '1', '-o', 'hello', '--opt2', '10', '-f']) assert arg1 == 'value1' assert arg2 == 1 assert opt1 == 'hello' assert opt2 == 10 assert opt3 == 'default' assert flag is True def test_invocation_from_argv(): @autoparse def func(arg1, arg2: int): return arg1, arg2 with patch('sys.argv', ['command', '1', '2']): arg1, arg2 = func() assert arg1 == "1" assert arg2 == 2 def test_description_epilog_help(check_help_text): @autoparse( description='this is a description', epilog='this is an epilog') def func(arg: 'this is help text'): pass check_help_text( lambda: func(['-h']), 'this is a description', 'this is an epilog', 'this is help text') def test_docstring_description(check_help_text): @autoparse def func(arg): '''This is a docstring description''' pass check_help_text( lambda: func(['-h']), 'This is a docstring description') def test_docstring_description_epilog(check_help_text): @autoparse def func(arg): ''' This is the description ------- This is the epilog ''' pass created_parser = func.parser assert 'This is the description' in created_parser.description assert 'This is the epilog' in created_parser.epilog check_help_text( lambda: func(['-h']), 'This is the description', 'This is the epilog', reject='-------') def test_bad_docstring(): with pytest.raises(TooManySplitsError): @autoparse def func(arg): ''' Part 1 ------- Part 2 ------- Part 3 ''' pass def test_custom_parser(): parser = ArgumentParser() parser.add_argument('arg', nargs='?') group = parser.add_mutually_exclusive_group() group.add_argument('-v', '--verbose', action='store_true') group.add_argument('-q', '--quiet', action='store_true') @autoparse(parser=parser) def main(arg, verbose, quiet): return arg, verbose, quiet assert main([]) == (None, False, False) assert main(['thing']) == ('thing', False, False) assert main(['-v']) == (None, True, False) assert main(['-q']) == (None, False, True) assert main(['-v', 'thing']) == ('thing', True, False) with pytest.raises(SystemExit): main(['-v', '-q']) autocommand-2.2.2/test/test_autoparse/test_single_flags.py000066400000000000000000000030601433575454400241300ustar00rootroot00000000000000import pytest @pytest.mark.parametrize("cli_args", [ ['-aFoo'], ['-a', 'Foo'], ['--arg=Foo'], ['--arg', 'Foo'] ]) def test_optional_flag_styles(check_parse, cli_args): check_parse( lambda arg="default_value": None, *cli_args, arg="Foo") def test_capitalizer(check_parse): check_parse( lambda arg1="", arg2="", arg3="": None, '-a', 'value1', '-A', 'value2', '--arg3', 'value3', arg1='value1', arg2='value2', arg3='value3') def test_reverse_capitalizer(check_parse): check_parse( lambda Arg1="", Arg2="", Arg3="": None, '-A', 'value1', '-a', 'value2', '--Arg3', 'value3', Arg1='value1', Arg2='value2', Arg3='value3') def test_single_letter_param(check_parse): def func(a=''): pass check_parse( func, '-a', 'value', a='value') with pytest.raises(SystemExit): check_parse( func, '--a', 'value', a='value') def test_single_letter_prioritized(check_parse): ''' Check that, when deciding which flags get to have single-letter variants, single-letter function parameters are assigned a letter first, so they aren't recapitalized or forced to have double-dash flags. ''' check_parse( lambda arg1='', arg2='', a='': None, '-a', 'value1', '-A', 'value2', '--arg2', 'value3', a='value1', arg1='value2', arg2='value3') def test_h_reserved(check_parse): check_parse( lambda hello='': None, '-H', 'value', hello='value') autocommand-2.2.2/test/test_autoparse/test_smart_open.py000066400000000000000000000022571433575454400236510ustar00rootroot00000000000000from autocommand.autoparse import smart_open def test_smart_open_is_exported(): import autocommand assert autocommand.smart_open is smart_open def test_smart_open_path_read(tmpdir): target = tmpdir.join('file.txt') target.write("Hello") with smart_open(str(target)) as file: assert not file.closed assert file.read() == "Hello" assert file.closed def test_smart_open_path_write(tmpdir): target = tmpdir.join('file.txt').ensure(file=True) with smart_open(str(target), 'w') as file: assert not file.closed file.write("Test Content") # Tests that the file is writable assert file.closed assert target.read() == "Test Content" def test_smart_open_path_create(tmpdir): target = tmpdir.join("file.txt") with smart_open(str(target), 'w') as file: file.write("Test Content") assert target.read() == "Test Content" def test_smart_open_file(tmpdir): path = str(tmpdir.join('file.txt').ensure(file=True)) with open(path) as file: with smart_open(file) as smart_file: assert file is smart_file assert not smart_file.closed assert not smart_file.closed autocommand-2.2.2/test/test_autoparse/test_types.py000066400000000000000000000042451433575454400226450ustar00rootroot00000000000000import pytest def test_int_positional(check_parse): def func(arg: int): pass check_parse( func, "1", arg=1) with pytest.raises(SystemExit): check_parse( func, 'hello') def test_int_default(check_parse): def func(arg=10): pass check_parse(func, "-a1", arg=1) check_parse(func, arg=10) with pytest.raises(SystemExit): check_parse(func, "-aHello") def test_int_none_default(check_parse): def func(arg: int =None): pass check_parse(func, '-a1', arg=1) check_parse(func, arg=None) with pytest.raises(SystemExit): check_parse(func, '-aHello') # A note on bool types: when the type is EXPLICITLY bool, then the parameter is # flag no matter what. If the flag is present on the CLI, the default is NOT # used; this is the most internally consistent behavior (no flag -> default, # flag -> nondefault). The "truthiness" of the default is used to determine # the nondefault value- falsy values like `None`, `0`, and `[]` result in True # being nondefault, while "truthy" values like `1`, `[1]`, and `'hello'` result # in False being nondefault. def make_bool_test_params(): def bool1(flag=False): pass def bool2(flag=True): pass def bool3(flag: bool): pass def bool4(flag: bool =None): pass def bool5(flag: bool =0): pass def bool6(flag: bool ='noflag'): pass return [ (bool1, True, False), (bool2, False, True), (bool3, True, False), (bool4, True, None), (bool5, True, 0), (bool6, False, 'noflag')] @pytest.mark.parametrize( 'function, with_flag, without_flag', make_bool_test_params() ) def test_bool(check_parse, function, with_flag, without_flag): check_parse(function, '-f', flag=with_flag) check_parse(function, '--flag', flag=with_flag) check_parse(function, flag=without_flag) def test_file(check_parse, tmpdir): filepath = tmpdir.join('test_file.txt') filepath.ensure(file=True) with filepath.open() as file: def func(input_file=file): pass check_parse(func, input_file=file) check_parse(func, "-i", "path/to/file", input_file="path/to/file") autocommand-2.2.2/test_requirements.txt000066400000000000000000000000541433575454400203640ustar00rootroot00000000000000pytest coverage pytest-cov coveralls flake8 autocommand-2.2.2/util/000077500000000000000000000000001433575454400150175ustar00rootroot00000000000000autocommand-2.2.2/util/README.md000066400000000000000000000001351433575454400162750ustar00rootroot00000000000000Util ==== This directory contains scripts for building, testing, and deploying autocommand. autocommand-2.2.2/util/test.sh000077500000000000000000000002741433575454400163400ustar00rootroot00000000000000#!/bin/sh set -ex python3 -m flake8 --show-source src test py.test \ --cov autocommand \ --cov-report term-missing \ --cov-config .coveragerc \ --strict \ "$@" test