Commits

Anonymous committed 0188411 Draft

Added documentation for the new feature.

Comments (0)

Files changed (1)

argparse_config.src/README.rst

 Let's say I'm reimplementing the Mercurial commandline client. I specify the
 commandline argument processing with ``argparse``, of course::
 
-    arg_parser = ArgumentParser('hg')
-    arg_parser.add_argument('--repository')
-    sub_parsers = arg_parser.add_subparsers()
-
-    merge_parser = sub_parsers.add_parser('merge')
-    merge_parser.add_argument('--tool')
-    merge_parser.add_argument('--force', type='store_const', const=True, default=False)
-
-    commit_parser = sub_parsers.add_parser('commit')
-    commit_parser.add_argument('--user')
-    commit_parser.add_argument('--message')
+    >>> arg_parser = ArgumentParser('hg')
+    >>> arg_parser.add_argument('--repository')
+    >>> sub_parsers = arg_parser.add_subparsers()
+    >>>
+    >>> merge_parser = sub_parsers.add_parser('merge')
+    >>> merge_parser.add_argument('--tool')
+    >>> merge_parser.add_argument('--force', action='store_true', default=False)
+    >>>
+    >>> commit_parser = sub_parsers.add_parser('commit')
+    >>> commit_parser.add_argument('--user')
+    >>> commit_parser.add_argument('--message')
 
 When I go to use this client, though, I have to keep specifying my ``--user``
 with every commit, and ``--tool`` with every merge. That sucks! What I want is
 is the equivalent of ``--verbose``. Either `verbose:` or `verbose` will work,
 but (watch out!) `verbose: a-value` doesn't do anything different to `verbose`.
 
+Writing a config file from some commandline arguments
+-----------------------------------------------------
+
+Included in the package is a utility to generate a config file following these
+rules, from a given set of commandline arguments. That looks like this::
+
+    >>> parsed_args = arg_parser.parse_args(['--repository', 'https://bitbucket.org/tikitu/argparse_config', 'merge'])
+    >>> print argparse_config.generate_config(arg_parser, parsed_args, only_non_defaults=True)
+    [default]
+    repository: https://bitbucket.org/tikitu/argparse_config
+
+    [merge]
+
+    [commit]
+
+Some complications make this less useful than it could be, sadly:
+
+* If you use subcommands, you can only parse the args for one of them at a time.
+* We can't tell the difference between default values written in code (which should
+  not be added to the config file) and written in a previously-read-in config file
+  (which should). This is why `only_non_defaults` exists.
+
 How does it work?
 -----------------