Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add an HTTPX cli. 😇 #1212

Closed
wants to merge 31 commits into from
Closed

Add an HTTPX cli. 😇 #1212

wants to merge 31 commits into from

Conversation

tomchristie
Copy link
Member

@tomchristie tomchristie commented Aug 21, 2020

Given just how wonderful the click and rich packages are these days, we could do some pretty wonderful stuff with an httpx command line tool, pretty easily.

Here's a pull request that demonstrates the basics, along with a couple of examples.

Installation is pip install httpx[cli].

Then we get:

$ httpx https://www.example.org

Screenshot 2020-08-21 at 16 17 25

$ httpx https://httpbin.org/post -m POST -j '{"hello": "world"}'

Screenshot 2020-08-21 at 16 17 06

Obviously there's more too it that this, in particular you'd want...

  • Controls for changing what output we display (eg. response headers, request line, redirects etc...)
  • Nice handling of how we display the possible error types.

And a few bits of other functionality, such as...

  • --stream - Disable formatting, and just display the content as it arrives.
  • --upload - Set upload content directly from a file.
  • --download - Download directly to a file. Default to displaying a progress bar if we're on a terminal display.
  • --raise-for-status - Return a non-zero error code, and display as an error, rather than the response itself.
  • --max-redirects, --http2 - Client-level controls that are not available in httpx.request, but that we might want in the cli.
  • Authentication controls. Haven't quite figured out how they'd look, since there's a few different options.

But some things that I think are nice about this are:

  • Just how much value we'd be getting for relatively minimal effort.
  • Having a really clean mapping between the CLI options and the httpx API, which I think could really help users get to grips with both of them.

Normally I might think of this kind of thing as scope-creep, but if we can make it tie in really nicely, then perhaps it's just a really nice way to make httpx an all-round more valuable tool?

Obvs. https://httpie.org/ exists and is fantastic, but I can still see the value in us presenting an alternative here, right?

@willmcgugan
Copy link
Contributor

Feel free to mention @willmcgugan if you have any questions re the Rich side of things. :)

@tomchristie tomchristie added the enhancement New feature or request label Sep 1, 2020
@tomchristie
Copy link
Member Author

Lookin nice... ⚡️

CJLhe08ZzO

@StephenBrown2
Copy link
Contributor

Rivaling httpie in no time!

@tomchristie
Copy link
Member Author

tomchristie commented Sep 16, 2020

Some TODO items...

  • Support --upload [FILE] for uploading content from file.
  • Support --stream for streaming output to console as soon as available. (Won't use syntax highlighting)
  • Support --session [FILE] for persistent cookie sessions.
  • Support --verify [FILE].
  • Support --cert [FILE] for client signing.
  • Support --auth-scheme [basic|digest].
  • Support --version.
  • Customize --help, using rich for formatting.
  • Transfer speed with rich.progress doesn't look correct to me. Moves around too much. Value can revise downwards once the download completes. See Bump up the total number of ProgressSample items. Textualize/rich#286
  • --verbose should also display request body.
  • --verbose should also display any additional auth, redirect requests. Requires auth/redirect hooks.
  • Syntax highlighting should preserve console background colour. See [REQUEST] Syntax highlighting using standard ANSI colours. Textualize/rich#284
  • Downloads with an indeterminate size (ie. No Content-Length) do not currently display correctly.
  • Add to docs.
  • Check method and body parameters for sensible request styles, and allow --force overrides.

@tomchristie tomchristie mentioned this pull request Sep 21, 2020
4 tasks
def print_request_headers(request: httpx.Request) -> None:
console = rich.console.Console()
http_text = format_request_headers(request)
syntax = rich.syntax.Syntax(http_text, "http", theme="ansi_dark", word_wrap=True)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any particular reason for going with theme="ansi_dark" instead of background_color="default"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either the ansi_light and ansi_dark themes render okay on both light and dark console backgrounds...

Screenshot 2020-09-22 at 09 19 56

Screenshot 2020-09-22 at 09 20 02

Using background_color="default" is really nice with monokai on dark consoles, but terrible on light backgrounds...

Screenshot 2020-09-22 at 09 18 19

Screenshot 2020-09-22 at 09 18 05

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha. I have a dark terminal, so I preferred the default theme. Perhaps adding a --theme={default,dark,light} option could be an thing?

@tomchristie
Copy link
Member Author

So, perhaps the route to go down here is to publish this under a separate httpx-cli package?
We could still include it prominently in the httpx docs, but it'd just be packaged separately.

The benefit there would be that we're not tied to bumping up httpx versions when we add new stuff to the client, and our 1.0 release doesn't have a whole bunch of extra considerations for us to make wrt. the cli interface.

@tomchristie
Copy link
Member Author

Closing this, in favour of a little beta over here: https://github.com/encode/httpx-cli

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants