Allow adding functions to parser without decorators

[neithere]

Current state

Functions cannot be assembled without decorators:

#!python
@command
def simple_one(): pass

@command 
def simple_two(a): pass

@command 
def simple_three(a=1): pass

# function with a merged explicit argument
@arg('-a', '--a', help='foo')
@command 
def simple_four(a=1): pass

# WRONG. this will raise an error
@arg('-x')
@command 
def simple_five(y): pass

Functions that expect a namespace object are considered "normal" despite being a marginal case and looking unpythonic:

#!python
def namespace_one(args): pass

@arg('a')
def namespace_two(args): pass

Desired state

Functions can be assembled without decorators:

#!python
# function with no arguments
def simple_one(): pass

# functions with arguments
def simple_two(a): pass
def simple_three(a=1): pass

# function with a merged explicit argument
@arg('-a', '--a', help='foo')
def simple_four(a=1): pass

# WRONG. this will raise an error
@arg('-x')
def simple_five(y): pass

Functions that expect a namespace object are a special case despite being "classic" from the argparse POV:

#!python
@expects_obj
def namespace_one(args): pass

@arg('a')
@expects_obj
def namespace_two(args): pass

Two possible improvements which I consider "magic" and generally unnecessary and therefore prefer to omit:

1. detect "classic" command function by signature ("arg" as the first and only argument);
2. restrict NS-expecting functions (via expects_obj() deco) to only have a single argument called args.

Note: This issue has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-24 08:55:32+00:00, last updated: 2012-12-30 16:34:04+00:00

[neithere]

Additions:

Varargs

#!python
def cmd(*paths):
    pass

# ...is the same as:

@arg('paths', nargs='*')
def cmd(paths):
    pass

# ...and same as:

@arg('paths', nargs='*')
@expects_obj
def cmd(args):
    pass

Keywords

**kwargs contains all arguments not fitting ArgSpec.args and ArgSpec.varargs. If ArgSpec.keywords in None, all @arg()'s will have to fit ArgSpec.args.

#!python

@arg('foo')
@arg('--bar', default=1)
def cmd(**kwargs):
    pass

# ...is the same as:

def cmd(foo, bar=1):
    pass

# ...and same as:

@arg('foo')
@arg('--bar', default=1)
@expects_obj
def cmd(args):
    pass

The first block does not require a default value to be specified.

Note: This comment has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-26 09:15:24+00:00, last updated: 2012-12-26 16:01:27+00:00

[neithere]

Backwards Compatibility

1. The command() decorator becomes no-op. It may set an attribute though, see below. A deprecation warning is raised.
2. If a function is not wrapped in command() and expects a single argument named args, it is likely to follow the old convention, i.e. implicitly expects a namespace object by default. After Argh is upgraded such function will break unless wrapped in expects_obj(). Therefore set_default_function() automatically wraps such function in expects_obj() to ease transition between the versions of API. A deprecation warning is raised.

Release 1.0 removes the command() decorator and the "magical" wrapping of func(args) in expects_obj().

Note: This comment has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-27 07:45:46+00:00

[neithere]

As DeprecationWarning is no longer loud since Python 2.7, it is required that the application developer runs the code as follows to ensure that the code is up to date:

#!bash
$ python -Wd app.py

Note: This comment has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-27 10:38:48+00:00

[neithere]

Re issue #29: implement new-style API, deprecate old functions, add compat fixes

Introspection/merging of varargs and keywords is not supported yet.

→ <>

Note: This comment has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-27 16:11:31+00:00

[neithere]

Re #29: add support for varargs.

→ <<cset 915a6aa05981>>

Note: This comment has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-27 16:18:35+00:00

[neithere]

Re #29: add support for varkw.

→ <>

Note: This comment has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-27 16:18:35+00:00

[neithere]

Well, the feature seems to be fully implemented and tested enough. Sure the code needs some refactoring and there are bugs yet to be found, but the issue can be closed.

Note: This comment has been automatically migrated from Bitbucket
Created by @neithere on 2012-12-30 16:34:04+00:00