NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #3355 most downloaded on PyPI
Plain Python functions as CLI commands without boilerplate
Last release 2 years ago
no release in 18 months
Ships unpredictably
gaps range from 9 days to 6.8 years
Some releases are documented
notes for 22 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
16 years old
65 releases · first in 2010
Fix type annotation of errors in wrap_errors by @laazy in #229
errors in wrap_errors by @laazy in #229Full changelog: https://argh.readthedocs.io/en/latest/changes.html#version-0-31-3-2024-07-13
Full diff: v0.31.2...v0.31.3
One column per quarter.
Bugs fixed:
wrong type annotation of errors in wrap_errors (PR #229 by @laazy)
tests were failing under Python 3.13 (issue #228 by @mgorny)
regression: can't set argument name with dest via decorator (issue #224 by @mathieulongtin)
broken support for Optional[List] (but not Optional[list] ), a narrower case of the problem fixed earlier (issue #216 ) by @neithere , thanks to @thor
Bugs fixed:
Optional[List] (but not Optional[list]), a narrower case of the problem fixed earlier (issue #216) by @neithere, thanks to @thorwhalenFull changelog: https://argh.readthedocs.io/en/latest/changes.html
Full diff: v0.31.1...v0.31.2
This text is a brief summary of the full changelog entry: https://argh.readthedocs.io/en/latest/changes.html#version-0-31-1-2024-01-19
This text is a brief summary of the full changelog entry: https://argh.readthedocs.io/en/latest/changes.html#version-0-31-1-2024-01-19
Bugs fixed:
List (issue #216), thanks to @thorwhalen.Enhancements:
Full diff: v0.31.0...v0.31.1
Bugs fixed:
broken support for type alias List (issue #216).
Enhancements:
cleaned up the README, rearranged other documentation.
Removed the previously deprecated decorator @expects_obj .
This release is a major step forward for Argh. It paves the way to a fully annotations-driven approach where decorators will remain a mere legacy.
This text is a brief summary of the full changelog entry: https://argh.readthedocs.io/en/latest/changes.html#version-0-31-0-2023-12-30
Breaking changes:
@arg decorator.BY_NAME_IF_HAS_DEFAULT concerning the order of variadic positional vs. keyword-only arguments.@expects_obj.Enhancements:
argh.dispatch_command() and argh.dispatch_commands()old_name_mapping_policy.Deprecated:
namespace argument in argh.dispatch() and argh.parse_and_resolve().Other changes:
Full Diff: v0.30.5...v0.31.0
Breaking changes:
The typing hints introspection feature is automatically enabled for any command (function) which does not have any arguments specified via @arg decorator.
This means that, for example, the following function used to fail and now it will pass:
def main(count: int):
assert isinstance(count, int)
This may lead to unexpected behaviour in some rare cases.
A small change in the legacy argument mapping policy BY_NAME_IF_HAS_DEFAULT concerning the order of variadic positional vs. keyword-only arguments.
The following function now results in main alpha [args ...] beta instead of main alpha beta [args ...]:
def main(alpha, *args, beta): ...
This does not concern the default name mapping policy. Even for the legacy one it's an edge case which is extremely unlikely to appear in any real-life application.
Removed the previously deprecated decorator @expects_obj.
Enhancements:
Added experimental support for basic typing hints (issue #203)
The following hints are currently supported:
str, int, float, bool (goes to type);
list (affects nargs), list[T] (first subtype goes into type);
Literal[T1, T2, ...] (interpreted as choices);
Optional[T] AKA T | None (currently interpreted as required=False for optional and nargs="?" for positional arguments; likely to change in the future as use cases accumulate).
The exact interpretation of the type hints is subject to change in the upcoming versions of Argh.
Added always_flush argument to dispatch() (issue #145)
High-level functions argh.dispatch_command() and argh.dispatch_commands() now accept a new parameter old_name_mapping_policy. The behaviour hasn't changed because the parameter is True by default. It will change to False in Argh v.0.33 or v.1.0.
Deprecated:
the namespace argument in argh.dispatch() and argh.parse_and_resolve(). Rationale: continued API cleanup. It's already possible to mutate the namespace object between parsing and calling the endpoint; it's unlikely that anyone would need to specify a custom namespace class or pre-populate it before parsing. Please file an issue if you have a valid use case.
Other changes:
Refactoring.
fix: nargs + list as default value ( #212 ) by @neithere in #213 (thanks to @pioio for bug report)
nargs is not specified but the default value is a list, nargs="*" is assumed and passed to argparse.Full Changelog: v0.30.4...v0.30.5
Please refer to the official changelog for more details: https://argh.readthedocs.io/en/latest/changes.html
Bugs fixed:
A combination of nargs with a list as default value would lead to the values coming from CLI being wrapped in another list (issue #212).
Enhancements:
Argspec guessing: if nargs is not specified but the default value is a list, nargs="*" is assumed and passed to argparse.
There were complaints about the lack of a deprecation cycle for the legacy name mapping policy. This version addresses the issue:
There were complaints about the lack of a deprecation cycle for the legacy name
mapping policy. This version addresses the issue:
The handling introduced in v.0.30.2 (raising an exception for clarity)
is retained for cases when no name mapping policy is specified but function
signature contains defaults in non-kwonly args and kwonly args are also
defined::
def main(alpha, beta=1, *, gamma=2): # error — explicit policy required
In a similar case but when kwonly args are not defined Argh now assumes
the legacy name mapping policy (BY_NAME_IF_HAS_DEFAULT) and merely issues
a deprecation warning with the same message as the exception mentioned above::
def main(alpha, beta=2): # `[-b BETA] alpha` + DeprecationWarning
This ensures that most of the old scripts still work the same way despite the
new policy being used by default and enforced in cases when it's impossible
to resolve the mapping conflict.
Please note that this "soft" handling is to be removed in version v0.33
(or v1.0 if the former is not deemed necessary). The new name mapping policy
will be used by default without warnings, like in v0.30.
— by @neithere
Full Changelog: v0.30.3...v0.30.4
fix: regression — @arg deco failing with underscore in positional arg name (fixes #208 ) by @neithere in #209 (thanks to @kaetir for a report with a r
@arg deco failing with underscore in positional arg name (fixes #208) by @neithere in #209 (thanks to @kaetir for a report with a reproducible example)Full Changelog: v0.30.2...v0.30.3
Bugs fixed:
Regression: a positional argument with an underscore used in @arg decorator would cause Argh fail on the assembling stage. (#208)
fix: raise exception for non-migrated commands (fixes #206 ) by @neithere (reported and valuable feedback given by @valentin-feron ) in #207
Full Changelog: v0.30.1...v0.30.2
Bugs fixed:
As reported in #204 and #206, the new default name mapping policy in fact silently changed the CLI API of some scripts: arguments which were previously translated as CLI options became optional positionals. Although the instructions were supplied in the release notes, the upgrade may not necessarily be intentional, so a waste of users' time is quite likely.
To alleviate this, the default value for name_mapping_policy in standard functions has been changed to None; if it's not specified, Argh falls back to the new default policy, but raises ArgumentNameMappingError with detailed instructions if it sees a non-kwonly argument with a default value.
Please specify the policy explicitly in order to avoid this error if you need to infer optional positionals (nargs="?") from function signature.
Regression: certain special values in argument default value would cause an exception ( #204 reported by @mfussenegger , fixed by @neithere )
Bugs fixed:
Enhancements:
Other changes:
py.typed marker file for PEP-561 by @neithereCommits: v0.30.0...v0.30.1
Full changelog: https://argh.readthedocs.io/en/latest/changes.html#version-0-30-1
Bugs fixed:
Regression: certain special values in argument default value would cause an exception (#204)
Enhancements:
Improved the tutorial.
Added a more informative error message when the reason is likely to be related to the migration from Argh v0.29 to a version with a new argument name mapping policy.
Other changes:
Added py.typed marker file for 561.
Remove previously deprecated code (closes #184 ) by @neithere in #188
help command alias and @expects_obj decorator by @neithere in #192Full Changelog: v0.29.4...v0.30.0
Backwards incompatible changes:
A new policy for mapping function arguments to CLI arguments is used by default (see argh.assembling.NameMappingPolicy).
The following function does not map to func foo [--bar] anymore:
def func(foo, bar=None):
...
Since this release it maps to func foo [bar] instead. Please update the function this way to keep bar an "option":
def func(foo, *, bar=None):
...
If you cannot modify the function signature to use kwonly args for options, please consider explicitly specifying the legacy name mapping policy:
set_default_command(
func, name_mapping_policy=NameMappingPolicy.BY_NAME_IF_HAS_DEFAULT
)
The name mapping policy BY_NAME_IF_HAS_DEFAULT slightly deviates from the old behaviour. Kwonly arguments without default values used to be marked as required options (--foo FOO), now they are treated as positionals (foo). Please consider the new default policy (BY_NAME_IF_KWONLY) for a better treatment of kwonly.
Removed previously deprecated features (#184 → #188):
argument help string in annotations — reserved for type hints;
argh.SUPPORTS_ALIASES;
argh.safe_input();
previously renamed arguments for add_commands(): namespace, namespace_kwargs, title, description, help;
pre_call argument in dispatch(). The basic usage remains simple but more granular functions are now available for more control.
Instead of this:
argh.dispatch(..., pre_call=pre_call_hook)
please use this:
func, ns = argh.parse_and_resolve(...) pre_call_hook(ns) argh.run_endpoint_function(func, ns, ...)
Deprecated:
The @expects_obj decorator. Rationale: it used to support the old, "un-pythonic" style of usage, which essentially lies outside the scope of Argh. If you are not using the mapping of function arguments onto CLI, then you aren't reducing the amount of code compared to vanilla Argparse.
The add_help_command argument in dispatch(). Rationale: it doesn't add much to user experience; it's not much harder to type --help than it is to type help; moreover, the option can be added anywhere, unlike its positional counterpart.
Enhancements:
Added support for Python 3.12.
Added type annotations to existing Argh code (#185 → #189).
The dispatch() function has been refactored, so in case you need finer control over the process, two new, more granular functions can be used:
endpoint_function, namespace = argh.parse_and_resolve(...)
argh.run_endpoint_function(endpoint_function, namespace, ...)
Please note that the names may change in the upcoming versions.
Configurable name mapping policy has been introduced for function argument to CLI argument translation (#191 → #199):
BY_NAME_IF_KWONLY (default and recommended).
BY_NAME_IF_HAS_DEFAULT (close to pre-v.0.30 behaviour);
Please check API docs on argh.assembling.NameMappingPolicy for details.
Remove previously deprecated code (closes #184) by @neithere in https://github.com/neithere/argh/pull/188
help command alias and @expects_obj decorator by @neithere in https://github.com/neithere/argh/pull/192Full Changelog: https://github.com/neithere/argh/compare/v0.29.4...v0.30.0-alpha
Test coverage reported as <100% when argcomplete is installed
Bugs fixed:
This is a technical release for packaging purposes.
This is a technical release for packaging purposes.
This is a technical release for packaging purposes.
This is a technical release for packaging purposes.
Add Github workflow to publish the release to PyPI by @neithere in https://github.com/neithere/argh/pull/167
Full Changelog: https://github.com/neithere/argh/compare/v0.28.0...v0.28.1
Thanks to everyone who reported
Deprecated features, to be removed in v.0.30:
A major modernisation and cleanup.
Backward incompatible changes:
Deprecated features, to be removed in v.0.30:
argh.assembling.SUPPORTS_ALIASES.
True for recent versions of Python.argh.io.safe_input() AKA argh.interaction.safe_input().
input() instead.argument pre_call in dispatch().
Even though this hack seems to have been used in some projects, it was never part of the official API and never recommended.
Describing your use case in the discussion about shared arguments (#63) can help improve the library to accomodate it in a proper way.
Argument help as annotations.
def func(foo: "Foobar"):
@arg('-f', '--foo', help="Foobar")
def func(foo):
Added deprecation warnings for some arguments deprecated back in v.0.26.
Full Changelog: https://github.com/neithere/argh/compare/v0.27.2...v0.28.0
Nothing published for this version
chore: include file required by tox.ini in the sdist
Minor packaging fix:
Minor building and packaging fixes:
Minor building and packaging fixes:
Contributors:
@mtelka (#155)
This is the last version to support Python 2.7.
This is the last version to support Python 2.7.
Backward incompatible changes:
Enhancements:
@wraps decorator (issue #111).Fixed bugs:
**kwargs and positionals without defaults and with underscores in their names, a weird behaviour could be observed (issue #104).unittest.mock (PR #154).skip_unknown_args=True (PR #134).Other changes:
Contributors:
@dwf (#105), @jwilk (#110), @jakirkham (#112), @brilee, @sanga (#116), @Gidgidonihah (#134), @mrdavidlaing (#153), @jelly (#154), @mtelka (#154), @hugovk (reviewing PRs).
This is a maintenance release. Just a few changes:
This is a maintenance release. Just a few changes:
The undocumented (and untested) argument dispatch(..., pre_call=x) was broken; fixing because at least one important app depends on it (issue #63).
Fixed bugs:
The undocumented (and untested) argument dispatch(..., pre_call=x) was broken; fixing because at least one important app depends on it (issue #63).
Removed decorator @alias (deprecated since v.0.19).
This release is intended to be the last one before 1.0. Therefore a major cleanup was done. This breaks backward compatibility. If your code is really outdated, please read this list carefully and grep your code.
@alias (deprecated since v.0.19).@plain_signature (deprecated since v.0.20).@expects_obj decorator is now mandatory for such functions.@command (deprecated since v.0.21).@wrap_errors decorator now strictly requires that the error classes
are given as a list (old behaviour was deprecated since v.0.22).allow_warnings argument is removed from
argh.completion.autocomplete(). Debug-level logging is used instead.
(The warnings were deprecated since v.0.25).Some more stuff has been scheduled to be purged before 1.0:
title, help and description in add_commands() helper function. See documentation and issue #60.Other changes:
add_subcommands() helper function (a convenience wrapper
for add_commands()).EntryPoint now stores kwargs for the parser.ArghNamespace object. It is used by default in ArghParser
and the shortcuts, but if you call the vanilla ArgumentParser.parse_args()
method, you now have to supply the proper namespace object.Fixed bugs:
Nothing published for this version
Shell completion warnings are now deprecated in favour of logging.
logging.Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →