From 6d3bbcea5713a7a868ba7e8def00ed18fda83b64 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Sun, 12 Apr 2015 20:24:12 +0200 Subject: [PATCH] docs(CLI): upload and output flag We are already there, except for documenting the request value type, which definitely deserves a separate issue. Fixes #45 --- src/mako/cli/docs/commands.md.mako | 51 +++++++++++++++++++++++++++++- src/mako/cli/lib/cli.py | 9 ++++++ src/mako/cli/lib/docopt.mako | 23 ++++++-------- 3 files changed, 68 insertions(+), 15 deletions(-) diff --git a/src/mako/cli/docs/commands.md.mako b/src/mako/cli/docs/commands.md.mako index 734761a535..dc4ec2b2b2 100644 --- a/src/mako/cli/docs/commands.md.mako +++ b/src/mako/cli/docs/commands.md.mako @@ -2,9 +2,12 @@ <%! from util import (hash_comment, new_context, method_default_scope, indent_all_but_first_by, is_repeated_property) from cli import (subcommand_md_filename, new_method_context, SPLIT_START, SPLIT_END, pretty, SCOPE_FLAG, - mangle_subcommand, is_request_value_property, FIELD_SEP, PARAM_FLAG) + mangle_subcommand, is_request_value_property, FIELD_SEP, PARAM_FLAG, UPLOAD_FLAG, docopt_mode, + FILE_ARG, MIME_ARG, OUT_ARG, OUTPUT_FLAG) from copy import deepcopy + + escape_html = lambda n: n.replace('>', r'\>') %>\ <% c = new_context(schemas, resources, context.get('methods')) @@ -38,6 +41,8 @@ You can set the scope for this method like this: `${util.program_name()} --${SCO <% rprops = [p for p in mc.required_props if not is_request_value_property(mc, p)] oprops = [p for p in mc.optional_props if not p.get('skip_example', False)] + + smd = mc.m.get('supportsMediaDownload', False) %>\ % if rprops: # Required Scalar ${len(rprops) > 1 and 'Arguments' or 'Argument'} @@ -76,6 +81,50 @@ can be set completely with the following arguments. Note how the cursor position * You can also set nested fields without setting the cursor explicitly. For example, to set the mapping from the root, you would specify `-r struct${FIELD_SEP}sub_struct${FIELD_SEP}mapping=foo=bar`. In case the cursor is not at the root, you may explicitly drill down from the root using a leading '${FIELD_SEP}' character. % endif # have request value +% if mc.media_params: +<% + protocols = [mp.protocol for mp in mc.media_params] +%>\ +# Required Upload Flags + +This method supports the upload of data, using the following protocol${len(mc.media_params) > 1 and 's' or ''}: + +* **-${UPLOAD_FLAG} ${docopt_mode(protocols)} ${escape_html(FILE_ARG)} ${escape_html(MIME_ARG)}** +% for mp in mc.media_params: + - **${mp.protocol}** - ${mp.description.split('\n')[0]} +% endfor # each media param + - **${escape_html(FILE_ARG)}** + + Path to file to upload. It must be seekable. + - **${escape_html(MIME_ARG)}** + + the mime type, like 'application/octet-stream', which is the default +% endif # have upload capabilities +% if mc.response_schema or smd: +# Optional Output Flags + +% if mc.response_schema: +The method's return value a JSON encoded structure, which will be written to standard output by default. +% endif +% if smd: + +% if mc.response_schema: +As this method supports **media download**, you may specify the `-${PARAM_FLAG} alt=media` flag to set the output to be an octet stream of the underlying media. In that case, you will not receive JSON output anymore. +% else: +The method's return value is a byte stream of the downloadable resource. +% endif # handle response schema +% endif # support media download + +* **-${OUTPUT_FLAG} ${escape_html(OUT_ARG)}** + - *${escape_html(OUT_ARG)}* specifies the *destination* to which to write the server's result to. +% if smd and mc.response_schema: + It will either be a JSON-encoded structure, or the media file you are downloading. +% elif smd: + It will be a byte stream of the downloadable resource. +% else: + It will be a JSON-encoded structure. +% endif + The *destination* may be `-` to indicate standard output, or a filepath that is to contain the received bytes. + If unset, it defaults to standard output. +% endif # have output % if oprops: # Optional Method Properties diff --git a/src/mako/cli/lib/cli.py b/src/mako/cli/lib/cli.py index 92a0f0115f..e6a97125db 100644 --- a/src/mako/cli/lib/cli.py +++ b/src/mako/cli/lib/cli.py @@ -14,6 +14,10 @@ OUTPUT_FLAG = 'o' VALUE_ARG = 'v' SCOPE_FLAG = 'scope' +FILE_ARG = '' +MIME_ARG = '' +OUT_ARG = '' + FIELD_SEP = '.' CONFIG_DIR = '~/.google-service-cli' @@ -51,6 +55,11 @@ def mangle_subcommand(name): def subcommand_md_filename(resource, method): return mangle_subcommand(resource) + '_' + mangle_subcommand(method) + '.md' +def docopt_mode(protocols): + mode = '|'.join(protocols) + if len(protocols) > 1: + mode = '(%s)' % mode + return mode # split the result along split segments def process_template_result(r, output_file): diff --git a/src/mako/cli/lib/docopt.mako b/src/mako/cli/lib/docopt.mako index e68e3e62a1..709fdf0335 100644 --- a/src/mako/cli/lib/docopt.mako +++ b/src/mako/cli/lib/docopt.mako @@ -2,12 +2,9 @@ <%! from util import (put_and, supports_scopes) from cli import (mangle_subcommand, new_method_context, PARAM_FLAG, STRUCT_FLAG, UPLOAD_FLAG, OUTPUT_FLAG, VALUE_ARG, - CONFIG_DIR, SCOPE_FLAG, is_request_value_property, FIELD_SEP) + CONFIG_DIR, SCOPE_FLAG, is_request_value_property, FIELD_SEP, docopt_mode, FILE_ARG, MIME_ARG, OUT_ARG) v_arg = '<%s>' % VALUE_ARG - file_arg = '' - mime_arg = '' - out_arg = '' %>\ <%def name="new(c)">\ <% @@ -37,10 +34,8 @@ Usage: if mc.media_params: upload_protocols = [mp.protocol for mp in mc.media_params] - mode = '|'.join(upload_protocols) - if len(mc.media_params) > 1: - mode = '(%s)' % mode - args.append('-%s %s %s %s' % (UPLOAD_FLAG, mode, file_arg, mime_arg)) + mode = docopt_mode(upload_protocols) + args.append('-%s %s %s %s' % (UPLOAD_FLAG, mode, FILE_ARG, MIME_ARG)) upload_protocols_used = upload_protocols_used|set(upload_protocols) # end upload handling @@ -49,8 +44,8 @@ Usage: param_used = True # end paramters - if mc.response_schema: - args.append('[-%s %s]' % (OUTPUT_FLAG, out_arg)) + if mc.response_schema or mc.m.get('supportsMediaDownload', False): + args.append('[-%s %s]' % (OUTPUT_FLAG, OUT_ARG)) output_used = True # handle output %>\ @@ -68,17 +63,17 @@ Options: 'field[${FIELD_SEP}subfield]...=value' to set an actual field. % endif % if upload_protocols_used: - -${UPLOAD_FLAG} ${file_arg} ${mime_arg} + -${UPLOAD_FLAG} ${FILE_ARG} ${MIME_ARG} may be one of the following upload modes: ${put_and(sorted(upload_protocols_used))} - ${file_arg} path to file to upload. It must be seekable. - ${mime_arg} the mime type, like 'application/octet-stream', + ${FILE_ARG} path to file to upload. It must be seekable. + ${MIME_ARG} the mime type, like 'application/octet-stream', which is the default % endif % if param_used: -${PARAM_FLAG} ${v_arg} set optional request parameter; ${v_arg} is of form 'name=value' % endif % if output_used: - -${OUTPUT_FLAG} ${out_arg} + -${OUTPUT_FLAG} ${OUT_ARG} The `destination` to which to write the server result to. It will either be a json-encoded structure, or the media file you are downloading.