From 79102699961960026b56229c7a66ba0f0acdcd15 Mon Sep 17 00:00:00 2001 From: Jakub Roztocil Date: Wed, 25 Apr 2012 02:10:58 +0200 Subject: [PATCH] Updated README and docs. --- README.rst | 73 ++++++++++++++++++++++++++++++---------------- httpie/__main__.py | 2 +- httpie/cli.py | 49 ++++++++++++++++++------------- 3 files changed, 78 insertions(+), 46 deletions(-) diff --git a/README.rst b/README.rst index 9c2ae2c6..0cb0ebee 100644 --- a/README.rst +++ b/README.rst @@ -106,31 +106,36 @@ Most of the flags mirror the arguments understood by ``requests.request``. See ` usage: http [-h] [--version] [--json | --form] [--traceback] [--pretty | --ugly] [--print OUTPUT_OPTIONS | --verbose | --headers | --body] - [--style STYLE] [--auth AUTH] [--verify VERIFY] - [--proxy PROXY] [--allow-redirects] [--timeout TIMEOUT] - METHOD URL [items [items ...]] + [--style STYLE] [--auth AUTH] [--auth-type {basic,digest}] + [--verify VERIFY] [--proxy PROXY] [--allow-redirects] + [--timeout TIMEOUT] + METHOD URL [ITEM [ITEM ...]] - HTTPie - cURL for humans. + HTTPie - cURL for humans. positional arguments: - METHOD HTTP method to be used for the request (GET, POST, + METHOD The HTTP method to be used for the request (GET, POST, PUT, DELETE, PATCH, ...). - URL Protocol defaults to http:// if the URL does not - include it. - items HTTP header (header:value), data field (field=value), - raw JSON field (field:=value) or file field - (field@/path/to/file). + URL The protocol defaults to http:// if the URL does not + include one. + ITEM A key-value pair whose type is defined by the + separator used. It can be an HTTP header + (header:value), a data field to be used in the request + body (field_name=value), a raw JSON data field + (field_name:=value) or a file field + (field_name@/path/to/file). You can use a backslash to + escape a colliding separator in the field name. optional arguments: -h, --help show this help message and exit --version show program's version number and exit - --json, -j Serialize data items as a JSON object and set Content- - Type to application/json, if not specified. - --form, -f Serialize fields as form values. The Content-Type is - set to application/x-www-form-urlencoded. The presence - of any file fields results into a multipart/form-data - request. Note that Content-Type is not automatically - set if explicitely specified. + --json, -j (default) Data items are serialized as a JSON object. + The Content-Type and Accept headers are set to + application/json (if not set via the command line). + --form, -f Data items are serialized as form fields. The Content- + Type is set to application/x-www-form-urlencoded (if + not specifid). The presence of any file fields results + into a multipart/form-data request. --traceback Print exception traceback should one occur. --pretty If stdout is a terminal, the response is prettified by default (colorized and indented if it is JSON). This @@ -139,12 +144,12 @@ Most of the flags mirror the arguments understood by ``requests.request``. See ` --ugly, -u Do not prettify the response. --print OUTPUT_OPTIONS, -p OUTPUT_OPTIONS String specifying what should the output contain. "H" - stands for request headers and "B" for request body. - "h" stands for response headers and "b" for response - body. Defaults to "hb" which means that the whole - response (headers and body) is printed. - --verbose, -v Print the whole request as well as response. Shortcut - for --print=HBhb. + stands for the request headers and "B" for the request + body. "h" stands for the response headers and "b" for + response the body. Defaults to "hb" which means that + the whole response (headers and body) is printed. + --verbose, -v Print the whole request as well as the response. + Shortcut for --print=HBhb. --headers, -t Print only the response headers. Shortcut for --print=h. --body, -b Print only the response body. Shortcut for --print=b. @@ -152,8 +157,15 @@ Most of the flags mirror the arguments understood by ``requests.request``. See ` Output coloring style, one of autumn, borland, bw, colorful, default, emacs, friendly, fruity, manni, monokai, murphy, native, pastie, perldoc, solarized, - tango, trac, vim, vs. Defaults to solarized. + tango, trac, vim, vs. Defaults to solarized. For this + option to work properly, please make sure that the + $TERM environment variable is set to "xterm-256color" + or similar (e.g., via `export TERM=xterm-256color' in + your ~/.bashrc). --auth AUTH, -a AUTH username:password + --auth-type {basic,digest} + The authentication mechanism to be used. Defaults to + "basic". --verify VERIFY Set to "no" to skip checking the host's SSL certificate. You can also pass the path to a CA_BUNDLE file for private certs. You can also set the @@ -166,6 +178,7 @@ Most of the flags mirror the arguments understood by ``requests.request``. See ` --timeout TIMEOUT Float describes the timeout of the request (Use socket.setdefaulttimeout() as fallback). + Contributors ------------ @@ -175,5 +188,15 @@ Contributors Changelog --------- -* `New in development version `_ +* `New in development version `_ +* 0.2.0 (2012-04-25) + * Added Python 3 support. + * Added the ability to print the HTTP request as well (see --print and --verbose). + * Added support for Digest authentication. + * Added file upload support (http -f POST file_field_name@/path/to/file). + * Improved syntax highlighting for JSON. + * Added support for field name escaping. + * Many bug fixes. + * `Complete changelog `_ + * `0.1.6 `_ (2012-03-04) diff --git a/httpie/__main__.py b/httpie/__main__.py index 5022a7bc..faa4045e 100644 --- a/httpie/__main__.py +++ b/httpie/__main__.py @@ -30,7 +30,7 @@ def _get_response(parser, args, stdin, stdin_isatty): if stdin_isatty: # Serialize the parsed data. args.data = json.dumps(args.data) - if args.method.lower() == 'get' and 'Accept' not in args.headers: + if 'Accept' not in args.headers: # Default Accept to JSON as well. args.headers['Accept'] = 'application/json' elif not args.files and 'Content-Type' not in args.headers: diff --git a/httpie/cli.py b/httpie/cli.py index 57433ed5..62ca44c2 100644 --- a/httpie/cli.py +++ b/httpie/cli.py @@ -3,8 +3,8 @@ CLI definition. """ from . import pretty -from . import __doc__ as doc -from . import __version__ as version +from . import __doc__ +from . import __version__ from . import cliparse @@ -13,8 +13,9 @@ def _(text): return ' '.join(text.strip().split()) -parser = cliparse.HTTPieArgumentParser(description=doc.strip(),) -parser.add_argument('--version', action='version', version=version) +desc = '%s ' +parser = cliparse.HTTPieArgumentParser(description=desc % __doc__.strip(),) +parser.add_argument('--version', action='version', version=__version__) # Content type. @@ -24,16 +25,17 @@ group_type = parser.add_mutually_exclusive_group(required=False) group_type.add_argument( '--json', '-j', action='store_true', help=_(''' - Serialize data items as a JSON object and set - Content-Type to application/json, if not specified. + (default) Data items are serialized as a JSON object. + The Content-Type and Accept headers + are set to application/json (if not set via the command line). ''') ) group_type.add_argument( '--form', '-f', action='store_true', help=_(''' - Serialize fields as form values. The Content-Type is set to application/x-www-form-urlencoded. + Data items are serialized as form fields. + The Content-Type is set to application/x-www-form-urlencoded (if not specifid). The presence of any file fields results into a multipart/form-data request. - Note that Content-Type is not automatically set if explicitely specified. ''') ) @@ -70,10 +72,10 @@ output_options.add_argument('--print', '-p', dest='output_options', default=cliparse.OUT_RESP_HEADERS + cliparse.OUT_RESP_BODY, help=_(''' String specifying what should the output contain. - "{request_headers}" stands for request headers and - "{request_body}" for request body. - "{response_headers}" stands for response headers and - "{response_body}" for response body. + "{request_headers}" stands for the request headers and + "{request_body}" for the request body. + "{response_headers}" stands for the response headers and + "{response_body}" for response the body. Defaults to "hb" which means that the whole response (headers and body) is printed. '''.format( @@ -87,7 +89,7 @@ output_options.add_argument( '--verbose', '-v', dest='output_options', action='store_const', const=''.join(cliparse.OUTPUT_OPTIONS), help=_(''' - Print the whole request as well as response. + Print the whole request as well as the response. Shortcut for --print={0}. '''.format(''.join(cliparse.OUTPUT_OPTIONS))) ) @@ -113,6 +115,9 @@ parser.add_argument( choices=pretty.AVAILABLE_STYLES, help=_(''' Output coloring style, one of %s. Defaults to solarized. + For this option to work properly, please make sure that the + $TERM environment variable is set to "xterm-256color" or similar + (e.g., via `export TERM=xterm-256color' in your ~/.bashrc). ''') % ', '.join(sorted(pretty.AVAILABLE_STYLES)) ) @@ -124,7 +129,7 @@ parser.add_argument( parser.add_argument( '--auth-type', choices=['basic', 'digest'], - help=_('The type of authentication ("basic" or "digest"). Defaults to "basic".') + help=_('The authentication mechanism to be used. Defaults to "basic".') ) parser.add_argument( @@ -167,19 +172,20 @@ parser.add_argument( parser.add_argument( 'method', metavar='METHOD', help=_(''' - HTTP method to be used for the request + The HTTP method to be used for the request (GET, POST, PUT, DELETE, PATCH, ...). ''') ) parser.add_argument( 'url', metavar='URL', help=_(''' - Protocol defaults to http:// if the - URL does not include it. + The protocol defaults to http:// if the + URL does not include one. ''') ) parser.add_argument( 'items', nargs='*', + metavar='ITEM', type=cliparse.KeyValueType( cliparse.SEP_COMMON, cliparse.SEP_DATA, @@ -187,8 +193,11 @@ parser.add_argument( cliparse.SEP_FILES ), help=_(''' - HTTP header (header:value), data field (field=value), - raw JSON field (field:=value) - or file field (field@/path/to/file). + A key-value pair whose type is defined by the separator used. It can be an + HTTP header (header:value), + a data field to be used in the request body (field_name=value), + a raw JSON data field (field_name:=value) + or a file field (field_name@/path/to/file). + You can use a backslash to escape a colliding separator in the field name. ''') )