Documented parameters.insert_value and pass_name.

clize/parameters.py

@@ -399,21 +399,21 @@ def argument_decorator(f):
         DecoratedArgumentParameter, kwargs={'decorator': f})
 
 
-class ConstantParameter(parser.ParameterWithSourceEquivalent):
+class InserterParameter(parser.ParameterWithSourceEquivalent):
     """Parameter that provides an argument to the called function without
     requiring an argument on the command line."""
 
     def __init__(self, value_factory,
                  undocumented, default, conv, aliases=None,
                  display_name='constant_parameter',
                  **kwargs):
-        super(ConstantParameter, self).__init__(
+        super(InserterParameter, self).__init__(
             undocumented=True, display_name=display_name, **kwargs)
         self.required = True
         self.value_factory = value_factory
 
 
-class ConstantPositionalParameter(ConstantParameter):
+class InserterPositionalParameter(InserterParameter):
     def read_argument(self, ba, i):
         ba.args.append(self.value_factory(ba))
         # Get the next pos parameter to process this argument
@@ -429,12 +429,12 @@ def unsatisfied(self, ba):
         ba.args.append(self.value_factory(ba))
 
 
-class ConstantNamedParameter(ConstantParameter):
+class InserterNamedParameter(InserterParameter):
     def unsatisfied(self, ba):
         ba.kwargs[self.argument_name] = self.value_factory(ba)
 
 
-def constant_value(value_factory):
+def value_inserter(value_factory):
     """Create an annotation that hides a parameter from the command-line
     and always gives it the result of a function.
 
@@ -443,16 +443,19 @@ def constant_value(value_factory):
         is passed as argument, ie. ``value_factory(ba)``.
     """
     uc = parser.use_class(
-        pos=ConstantPositionalParameter, named=ConstantNamedParameter,
+        pos=InserterPositionalParameter, named=InserterNamedParameter,
         kwargs={'value_factory': value_factory}
         )
     update_wrapper(uc, value_factory)
     return uc
 
 
-@constant_value
+@value_inserter
 def pass_name(ba):
-    """Parameters decorated with this will receive the script name as
-    argument."""
+    """Parameters decorated with this will receive the executable name as
+    argument.
+
+    This can be either the path to a python file, or ``python -m some.module``.    It is also appended with sub-command names.
+    """
     return ba.name
 

docs/reference.rst

@@ -593,6 +593,54 @@ Forcing arguments to be treated as positional
     the parameter ``d`` which had the annotation.
 
 
+.. _pass name:
+
+Retrieving the executable name
+..............................
+
+.. autofunction:: clize.parameters.pass_name
+
+    .. code-block:: python
+
+        from clize import run, parameters
+
+        def main(name:parameters.pass_name, arg):
+            print('name:', name)
+            print('arg:', arg)
+
+        def alt(arg, *, name:parameters.pass_name):
+            print('arg:', arg)
+            print('name:', name)
+
+        run(main, alt=alt)
+
+    .. x*
+
+    .. code-block:: console
+
+        $ python pn.py ham
+        name: pn.py
+        arg: ham
+        $ python -m pn ham
+        name: python -m pn
+        arg: ham
+        $ python pn.py --alt spam
+        arg: spam
+        name: pn.py --alt
+        $ python -m pn --alt spam
+        arg: spam
+        name: python -m pn --alt
+
+
+.. _constant value:
+
+Inserting arbitrary values
+..........................
+
+.. autofunction:: clize.parameters.constant_value
+
+
+
 .. _docstring:
 
 Customizing the help using the docstring