Added docstrings, refactored input.

README.rst

@@ -76,7 +76,7 @@ Raw JSON fields (``field:=value``)
   This item type is needed when ``Content-Type`` is JSON and a field's value
   is a ``Boolean``, ``Number``,  nested ``Object`` or an ``Array``, because
   simple data items are always serialized as ``String``.
-  E.g. ``pies:=[1,2,3]``,or ``'meals=["ham", "spam"]'`` (mind the quotes).
+  E.g. ``pies:=[1,2,3]``, or ``'meals=["ham", "spam"]'`` (mind the quotes).
 
 File fields (``field@/path/to/file``)
   Only available with ``-f`` / ``--form``. Use ``@`` as the separator, e.g.,

httpie/__main__.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python
-"""
-The main entry point. Invoke as `http' or `python -m httpie'.
+"""The main entry point. Invoke as `http' or `python -m httpie'.
 
 """
 import sys

httpie/cli.py

@@ -1,22 +1,24 @@
-"""
-CLI definition.
+"""CLI arguments definition.
+
+NOTE: the CLI interface may change before reaching v1.0.
 
 """
 from . import __doc__
 from . import __version__
-from . import cliparse
 from .output import AVAILABLE_STYLES
+from .input import (Parser, AuthCredentialsArgType, KeyValueArgType,
+                    PRETTIFY_STDOUT_TTY_ONLY,
+                    SEP_PROXY, SEP_CREDENTIALS, SEP_GROUP_ITEMS,
+                    OUT_REQ_HEAD, OUT_REQ_BODY, OUT_RESP_HEAD,
+                    OUT_RESP_BODY, OUTPUT_OPTIONS)
 
 
 def _(text):
-    """Normalize white space."""
+    """Normalize whitespace."""
     return ' '.join(text.strip().split())
 
 
-desc = '%s <http://httpie.org>'
-parser = cliparse.Parser(
-    description=desc % __doc__.strip(),
-)
+parser = Parser(description='%s <http://httpie.org>' % __doc__.strip())
 parser.add_argument('--version', action='version', version=__version__)
 
 
@@ -58,7 +60,7 @@ def _(text):
 prettify = parser.add_mutually_exclusive_group(required=False)
 prettify.add_argument(
     '--pretty', dest='prettify', action='store_true',
-    default=cliparse.PRETTIFY_STDOUT_TTY_ONLY,
+    default=PRETTIFY_STDOUT_TTY_ONLY,
     help=_('''
         If stdout is a terminal, the response is prettified
         by default (colorized and indented if it is JSON).
@@ -85,35 +87,35 @@ def _(text):
         If the output is piped to another program or to a file,
         then only the body is printed by default.
     '''.format(
-        request_headers=cliparse.OUT_REQ_HEAD,
-        request_body=cliparse.OUT_REQ_BODY,
-        response_headers=cliparse.OUT_RESP_HEAD,
-        response_body=cliparse.OUT_RESP_BODY,
+        request_headers=OUT_REQ_HEAD,
+        request_body=OUT_REQ_BODY,
+        response_headers=OUT_RESP_HEAD,
+        response_body=OUT_RESP_BODY,
     ))
 )
 output_options.add_argument(
     '--verbose', '-v', dest='output_options',
-    action='store_const', const=''.join(cliparse.OUTPUT_OPTIONS),
+    action='store_const', const=''.join(OUTPUT_OPTIONS),
     help=_('''
         Print the whole request as well as the response.
         Shortcut for --print={0}.
-    '''.format(''.join(cliparse.OUTPUT_OPTIONS)))
+    '''.format(''.join(OUTPUT_OPTIONS)))
 )
 output_options.add_argument(
     '--headers', '-h', dest='output_options',
-    action='store_const', const=cliparse.OUT_RESP_HEAD,
+    action='store_const', const=OUT_RESP_HEAD,
     help=_('''
         Print only the response headers.
         Shortcut for --print={0}.
-    '''.format(cliparse.OUT_RESP_HEAD))
+    '''.format(OUT_RESP_HEAD))
 )
 output_options.add_argument(
     '--body', '-b', dest='output_options',
-    action='store_const', const=cliparse.OUT_RESP_BODY,
+    action='store_const', const=OUT_RESP_BODY,
     help=_('''
         Print only the response body.
         Shortcut for --print={0}.
-    '''.format(cliparse.OUT_RESP_BODY))
+    '''.format(OUT_RESP_BODY))
 )
 
 parser.add_argument(
@@ -149,7 +151,7 @@ def _(text):
 # ``requests.request`` keyword arguments.
 parser.add_argument(
     '--auth', '-a',
-    type=cliparse.AuthCredentialsArgType(cliparse.SEP_CREDENTIALS),
+    type=AuthCredentialsArgType(SEP_CREDENTIALS),
     help=_('''
         username:password.
         If only the username is provided (-a username),
@@ -177,7 +179,7 @@ def _(text):
 )
 parser.add_argument(
     '--proxy', default=[], action='append',
-    type=cliparse.KeyValueArgType(cliparse.SEP_PROXY),
+    type=KeyValueArgType(SEP_PROXY),
     help=_('''
         String mapping protocol to the URL of the proxy
         (e.g. http:foo.bar:3128).
@@ -224,7 +226,7 @@ def _(text):
 parser.add_argument(
     'items', nargs='*',
     metavar='ITEM',
-    type=cliparse.KeyValueArgType(*cliparse.SEP_GROUP_ITEMS),
+    type=KeyValueArgType(*SEP_GROUP_ITEMS),
     help=_('''
         A key-value pair whose type is defined by the
         separator used. It can be an HTTP header (header:value),

httpie/core.py

@@ -1,3 +1,13 @@
+"""This module provides the main functionality of HTTPie.
+
+Invocation flow:
+
+    1. Read, validate and process the input (args, `stdin`).
+    2. Create a request and send it, get the response.
+    3. Process and format the requested parts of the request-response exchange.
+    4. Write to `stdout` and exit.
+
+"""
 import sys
 import json
 
@@ -7,15 +17,18 @@
 
 from .models import HTTPMessage, Environment
 from .output import OutputProcessor
-from . import cliparse
-from . import cli
+from .input import (PRETTIFY_STDOUT_TTY_ONLY,
+                    OUT_REQ_BODY, OUT_REQ_HEAD,
+                    OUT_RESP_HEAD, OUT_RESP_BODY)
+from .cli import parser
 
 
 TYPE_FORM = 'application/x-www-form-urlencoded; charset=utf-8'
 TYPE_JSON = 'application/json; charset=utf-8'
 
 
 def get_response(args, env):
+    """Send the request and return a `request.Response`."""
 
     auto_json = args.data and not args.form
     if args.json or auto_json:
@@ -69,23 +82,20 @@ def get_response(args, env):
         sys.exit(1)
 
 
-def get_output(args, env, response):
+def get_output(args, env, request, response):
+    """Format parts of the `request`-`response` exchange
+     according to `args` and `env` and return a `unicode`.
 
-    do_prettify = (
-        args.prettify is True or
-        (args.prettify == cliparse.PRETTIFY_STDOUT_TTY_ONLY
-        and env.stdout_isatty)
-    )
+    """
+    do_prettify = (args.prettify is True
+                   or (args.prettify == PRETTIFY_STDOUT_TTY_ONLY
+                       and env.stdout_isatty))
 
-    do_output_request = (
-        cliparse.OUT_REQ_HEAD in args.output_options
-        or cliparse.OUT_REQ_BODY in args.output_options
-    )
+    do_output_request = (OUT_REQ_HEAD in args.output_options
+                         or OUT_REQ_BODY in args.output_options)
 
-    do_output_response = (
-        cliparse.OUT_RESP_HEAD in args.output_options
-        or cliparse.OUT_RESP_BODY in args.output_options
-    )
+    do_output_response = (OUT_RESP_HEAD in args.output_options
+                          or OUT_RESP_BODY in args.output_options)
 
     prettifier = None
     if do_prettify:
@@ -95,21 +105,23 @@ def get_output(args, env, response):
     buf = []
 
     if do_output_request:
-        req = HTTPMessage.from_request(response.request).format(
+        req_msg = HTTPMessage.from_request(request)
+        req = req_msg.format(
             prettifier=prettifier,
-            with_headers=cliparse.OUT_REQ_HEAD in args.output_options,
-            with_body=cliparse.OUT_REQ_BODY in args.output_options
+            with_headers=OUT_REQ_HEAD in args.output_options,
+            with_body=OUT_REQ_BODY in args.output_options
         )
         buf.append(req)
         buf.append('\n')
         if do_output_response:
             buf.append('\n')
 
     if do_output_response:
-        resp = HTTPMessage.from_response(response).format(
+        resp_msg = HTTPMessage.from_response(response)
+        resp = resp_msg.format(
             prettifier=prettifier,
-            with_headers=cliparse.OUT_RESP_HEAD in args.output_options,
-            with_body=cliparse.OUT_RESP_BODY in args.output_options
+            with_headers=OUT_RESP_HEAD in args.output_options,
+            with_body=OUT_RESP_BODY in args.output_options
         )
         buf.append(resp)
         buf.append('\n')
@@ -118,10 +130,7 @@ def get_output(args, env, response):
 
 
 def get_exist_status(code, allow_redirects=False):
-    """
-    Translate HTTP status code to exit status.
-
-    """
+    """Translate HTTP status code to exit status."""
     if 300 <= code <= 399 and not allow_redirects:
         # Redirect
         return 3
@@ -136,13 +145,12 @@ def get_exist_status(code, allow_redirects=False):
 
 
 def main(args=sys.argv[1:], env=Environment()):
-    """
-    Run the main program and write the output to ``env.stdout``.
+    """Run the main program and write the output to ``env.stdout``.
 
     Return exit status.
 
     """
-    args = cli.parser.parse_args(args=args, env=env)
+    args = parser.parse_args(args=args, env=env)
     response = get_response(args, env)
 
     status = 0
@@ -155,7 +163,7 @@ def main(args=sys.argv[1:], env=Environment()):
                 response.raw.status, response.raw.reason)
             env.stderr.write(err.encode('utf8'))
 
-    output = get_output(args, env, response)
+    output = get_output(args, env, response.request, response)
     output_bytes = output.encode('utf8')
     f = getattr(env.stdout, 'buffer', env.stdout)
     f.write(output_bytes)