Concerning 1.0

[Andy Mikhaylenko]

Hello everyone!

Thanks for using the library and submitting tickets and patches. With your help Argh is approaching the first stable release.

Most issues assigned to version 1.0 are closed[1]. The remainder will soon be either fixed or postponed.

I'm doing my best to avoid breaking things despite the project is formally still unstable. There are some deprecated functions that should emit warnings but work as before.

WARNING: all things marked as deprecated will be removed by the first stable release.

Currently the only deprecated function is alias() which is replaced with aliases() and named().
The decorator plain_signature() is also likely to be removed in the near future.
All changes are documented[2].

I'll probably post another announcement with a summary of things to be removed, but please keep in mind that 1.0 will break backwards compatibility. Later releases (1.x) will be backwards compatible with 1.0, not 0.x.

[1] https://bitbucket.org/neithere/argh/issues?milestone=1.0
[2] http://packages.python.org/argh/reference.html#argh.decorators.alias

I hope updating your code will require minimum effort or even none.

Cheers,
Andy

[Andy Mikhaylenko]

Arrrgh everybody.

Good news.

Argh 0.21 is out. It introduces the "natural way" of declaring commands. This version also deprecates a set of features while keeping backward compatibility.

Argh 1.0 will be released in January 2013. It will be the first stable release.

WARNING: version 1.0 will *REMOVE* support for deprecated functions and conventions.

As Python ≥ 2.7 hides DeprecationWarning from end users, please try running your application as follows:

    $ python -Wd app.py {all possible commands one by one}

Here's a list of things to be *removed*:

1. the @alias decorator (use @named or @aliases instead);
2. the @plain_signature decorator (simply drop it);
3. the @command decorator (simply drop it);
4. support for old-style commands like func(args).

Old-style commands (functions that expect a namespace object) will *BREAK*.

You need to do one of the following:

a) wrap such functions in @expects_obj decorators, or
b) convert them to the new style (plain signature).

Please consult the updated documentation[1] including the rewritten tutorial[2].

See issue29[3] for details on the motivation and exact changes related to the "natural way" of defining commands.

[1] https://argh.readthedocs.org/en/latest/
[2] https://argh.readthedocs.org/en/latest/tutorial.html
[3] https://bitbucket.org/neithere/argh/issue/29/allow-adding-functions-without-decorators

I urge you to migrate your code before 1.0 is released. In fact, I'm holding it back to ensure that users have enough time for the migration.

Have a nice New Year.

Andy

[Andy Mikhaylenko]

Hello.

Argh 0.22.0 is out. Again, existing code needs to be checked for forward compatibility.

Introduced:

* basic support for class-based controllers[1];
* preprocessors for wrapped errors[2].

Deprecated:

* old-style listing of exception classes in `@wrap_errors`[2].

[1] https://bitbucket.org/neithere/argh/issue/34/class-methods-as-commands
[2] https://bitbucket.org/neithere/argh/issue/36/specify-preprocessor-for-wrapped-errors

To sum up, before Argh 1.0 is released, your code must be updated as follows:

1. replace the @alias decorator with @named or @aliases;
2. remove the @plain_signature decorator;
3. remove the @command decorator;
4. replace old-style commands like func(args) with "natural" ones or add @expects_obj;
5. replace @wrap_errors(E) with @wrap_errors([E])

Remember to check your code with `python -Wd`.

Cheers,
Andy

[Ted Stern]

Hi Andy,

I have a question about converting from the old func(args) mode.

I am working in Python 2 anyway, so I have @args decorators for all my functions already.

Can I just convert func(args) to func(*args) and be done with it?

Thanks, Ted

--
 
 

--
 Frango ut patefaciam -- I break so that I may reveal

[Andy Mikhailenko]

Hello Ted,

> Can I just convert func(args) to func(*args) and be done with it?

I'm afraid, no. Below I'll try to explain what *args is and what to do.

The "natural" notation:

def func(*xs):
pass

The decorator-based notation:

@arg('xs', nargs='*')
def func(xs):
pass

The CLI signature:

func [xs [xs ...]]

As you see, the `args` in `func(*args)` is a single argument that
accepts 0..n values (aka nargs='*').

Using a "catch-all" object (like an argparse.Namespace instance named
"args" or anything of the sort) is not pythonic in any way.

Still, there are valid cases when such objects are preferable and even
more DRY (e.g. when the whole function signature is duplicated with
@arg decorators). Here are two valid options:

@arg('foo')
@expects_obj
def func(ns): # "ns", "args" or whatever
print ns.foo

@arg('foo')
def func(**kwargs):
print kwargs['foo']

Adding the `@expects_obj` decorator is enough for the old-style
function to survive the update. If you have a set of old-style
commands, it may be a good idea to wrap them before assembling instead
of decorating:

old_commands = [foo, bar, baz, quux]
parser.add_commands([expects_obj(c) for c in old_commands])

This way the declarations can be left completely intact.

However, I would really consider switching to the more pythonic
syntax. Most @arg decorators only add help messages (because other
stuff is usually correctly inferred by Argh from the function
signature). If the argument names are well-thought and the whole CLI
is well-structured, there's little need it additional help.

Cheers,
Andy

[Andy Mikhaylenko]

Hi all,

Argh 0.23 is out. No new features were introduced but some behaviour has been changed and bugs fixed:

Fix #37: Wrapped errors should go to stderr
Fix #38: Tests that pass on source tree would fail in the package
Fix #39: Don't issue bash warnings when not using bash
...I've also fixed an output encoding bug and improved documentation.

At this point there are no remaining issues for milestone 1.0 except for #25: "Add reviews of similar projects", which is not important at all and will be simply postponed if I don't tackle it within a week or so.

This is the last backwards-compatible version.

The next version is planned to be 1.0 Release Candidate.  It will *drop* any deprecated functionality.  The list of actions required from application developers was published earlier in this thread.

Have a nice day!

Andy