Python API

[eliangcs]

HTTP Prompt* heavily relies on httpie.core.main() function to send actual HTTP requests. Some HTTP Prompt's features, like setting incoming cookies, require us to access the response object (requests.Response, to be more specific) in Python, but httpie.core.main() doesn't provide such an API. So HTTP Prompt "hacks" HTTPie with sys.settrace() to get the response object returned by httpie.core.get_response(), as the following code shows:

https://github.com/eliangcs/http-prompt/blob/cbd092299/http_prompt/execution.py#L430

I wonder if HTTPie could offer an API for developers to access the internal response object easier.

* For those who haven't already known: HTTP Prompt is a wrapper that provides an interactive interface of HTTPie.

[jkbrzt]

Yes, it makes sense — I'll look into this. main() could return both exit status code and the final HTTP response. And maybe the parse args as well would be useful to return as well.

[jkbrzt]

@eliangcs I'm doing a bigger refactoring and I'm thinking it would be good to have a stable and documented api.py module for use by third-party tools, so they don't have to touch the internals which have the tendency to change over time.

Could you maybe flash something out based on what http-prompt currently imports from HTTPie? Empty methods with args, and some brief docstrings with return values would be enough. A good starting point would be just listing all the imports http-prompt needs.

// cc @mblayman

[eliangcs]

@jkbrzt I did a grep over my codebase. These are what I found:

# http_prompt/cli.py
from httpie.plugins import FormatterPlugin  # just to avoid cyclic import, not really used
from httpie.output.formatters.colors import Solarized256Style  # to support solarized theme

# http_prompt/execution.py
from httpie.context import Environment  # to construct a custom Environment and pass it to httpie_main
from httpie.core import main as httpie_main  # to generate output and the response object

[mblayman]

HTTPony touches very little of HTTPie's APIs. It's limited to:

from httpie.cli import parser
from httpie.context import Environment
from httpie.output import streams

The core of what is done is passing a requests.models.Request to streams.build_output_stream and calling streams.write_stream. All that happens in https://github.com/mblayman/httpony/blob/master/httpony/application.py.

[jkbrzt]

Great, thanks. I'll go through it and to formalize those things where it makes sense. Then make some wrappers in httpie.api — or simply make those objects importable from the module to begin with.

This will make it explicit users can/might depend on it and provide some guarantee of stability compared to the internals. Changes to the httpie.api-exported functionality should also be covered in the change log.