From 85bbc570bd21af2f9d70a8db1c309d39974e50ca Mon Sep 17 00:00:00 2001 From: Andy Mikhaylenko Date: Wed, 15 Feb 2023 00:49:55 +0100 Subject: [PATCH] docs: deprecation of `dispatch(..., pre_call=...)` This is not in fact deprecation per se but merely an attempt to draw attention to a fact that was mentioned almost ten years ago in the discussion (#63): the `pre_call` argument in `dispatch()` is not a feature but a hack which is not recommended and will be removed. This commit makes it clear when precisely it is going to be removed and what actions are expected from the user. --- CHANGES | 10 ++++++++++ src/argh/dispatching.py | 16 ++++++++++++---- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/CHANGES b/CHANGES index 0a75af4..d987ef3 100644 --- a/CHANGES +++ b/CHANGES @@ -21,6 +21,16 @@ Deprecated features, to be removed in v.0.30: - Not relevant anymore. Please use the built-in `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`_ can + help improve the library to accomodate it in a proper way. + + .. _discussion about shared arguments: https://github.com/neithere/argh/issues/63 + - Argument help as annotations. - Annotations will only be used for types after v.0.30. diff --git a/src/argh/dispatching.py b/src/argh/dispatching.py index 513ad2d..80bf6e8 100644 --- a/src/argh/dispatching.py +++ b/src/argh/dispatching.py @@ -223,10 +223,18 @@ def _execute_command(function, namespace_obj, errors_file, pre_call=None): All other exceptions propagate unless marked as wrappable by :func:`wrap_errors`. """ - if pre_call: # XXX undocumented because I'm unsure if it's OK - # Actually used in real projects: - # * https://google.com/search?q=argh+dispatch+pre_call - # * https://github.com/neithere/argh/issues/63 + # TODO: remove in v.0.30 + if pre_call: # pragma: no cover + # This is NOT a documented and recommended API. + # The common use case for this hack is to inject shared arguments. + # Such approach would promote an approach which is not in line with the + # purpose of the library, i.e. to keep things natural and "pythonic". + # Argh is about keeping CLI in line with function signatures. + # The `pre_call` hack effectively destroys this mapping. + # There should be a better solution, e.g. decorators and/or some shared + # objects. + # + # See discussion here: https://github.com/neithere/argh/issues/63 pre_call(namespace_obj) # the function is nested to catch certain exceptions (see below)