Add Python API support

[giampaolo]

httpie is a very cool CLI tool, far better than curl.
It would be great if there would a minimal documented API support so that it can also be used as a Python module you can import and make requests with.
The way I would expect it to work might be something like this:

>>> from httpie import interpret_args
>>> resp = interpret_args("http GET http://localhost:8000/help")
>>> resp
<Response [200]>
>>> resp.status_code
200
>>> 

Thoughts?

[ticky]

Wouldn't you be better off just using Requests, which httpie is based upon?

>>> import requests
>>> resp = requests.get("http://localhost:8000/help")
>>> resp
<Response [200]>
>>> resp.status_code
200
>>> 

[giampaolo]

I see httpie as a very valuable language abstraction on top of requests.
With a single httpie line you can express concepts which you would otherwise express in 2-3-10 lines of requests/python code.
As such you can use it as an actual mini language, which you can even integrate into configuration files in form of a plain string (this is my use case actually, and this is why I'm here hehe).
Plus, if one is already proficient with httpie syntax it's easier for him to just integrate it in a python script by using an actual API as opposed to launching a subprocess and parsing its retcode and output, which is of course suboptimal.

[giampaolo]

I'm not sure if my idea fits well with all httpie usage patterns.
It probably works as long as it makes sense to have a Response object in return (instead of something else) which AFAICT is the case most of the times if not all.

[jkbrzt]

The interesting part of what HTTPie does in this regard is the translation of a command line argument list to the **kwargs passed to requests.request().

If it was to be exposed, then it would look something like this:

import requests
from httpie.cli import parser
from httpie.context import Environment
from httpie.client import get_requests_kwargs


def command_to_requests_kwargs(command):
    args = parser.parse_args(args=command.split(), env=Environment())
    return get_requests_kwargs(args)


kwargs = command_to_requests_kwargs("""
    --auth-type=digest  --auth=user:password'
    PUT httpbin.org/put
        Referer:example.org
        User-Agent:Bacon/1.0
""")


>>> kwargs
{'allow_redirects': False,
 'auth': <requests.auth.HTTPDigestAuth at 0x10db48ed0>,
 'cert': None,
 'data': OrderedDict(),
 'files': OrderedDict(),
 'headers': CaseInsensitiveDict({'Referer': 'example.org', 'User-Agent': 'Bacon/1.0'}),
 'method': 'patch',
 'params': ParamDict(),
 'proxies': {},
 'stream': True,
 'timeout': 30,
 'url': 'http://example.org/foo',
 'verify': True}

>>> requests.request(**kwargs)
<Response [405]>

HTTPie actually spits out the Python code used to make the request when the --debug flag is set:

$ http --debug --auth-type=digest --auth=user:password PATCH example.org/foo Referer:example.org User-Agent:Bacon/1.0
HTTPie 0.8.0
HTTPie data: /Users/jakub/.httpie
Requests 2.2.1
Pygments 1.6
Python 2.7.6 (default, Nov 21 2013, 11:09:15)
[GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.1.72)] darwin

>>> requests.request({'allow_redirects': False,
 'auth': <requests.auth.HTTPDigestAuth object at 0x10c8b8a10>,
 'cert': None,
 'data': OrderedDict(),
 'files': OrderedDict(),
 'headers': CaseInsensitiveDict({'Referer': 'example.org', 'User-Agent': 'Bacon/1.0'}),
 'method': 'patch',
 'params': ParamDict(),
 'proxies': {},
 'stream': True,
 'timeout': 30,
 'url': 'http://example.org/foo',
 'verify': True})

[felipevolpone]

I think that I could start the process to create an abstraction layer to provide httpie as an API. There is some task already in course to do this?

[ryneeverett]

Here's another use case I ran into in the wild: calling httpie in a subprocess just for the pretty printing and logging.

[Almad]

This is a duplicate to #551—let's use that one as a canonical issue.