extern/httpie-cli
1
0
Fork 1
mirror of https://github.com/httpie/cli.git synced 2025-06-24 03:21:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Man page fixes (#1364)

Browse Source 
- Highlighting for options (-x, --x) now doesn't strip the prefix (may be whitespace).
- Escape sequences are now cross-platform compatible (directly taken by groff/troff [man's renderer])
- Now we check for the section before displaying the man pages.
- On MacOS, there is HTTP(n) which is different from our HTTP(1). This used to conflict with it, and we showed the wrong page. Now we specifically ask foir HTTP(1).
- Errors that might happen (e.g non executable man command) is now suppressed. So in the worst case (if anything regarding man execution goes wrong), we'll always display the manual.
- Docs for man pages.
- HTTPie man pages.
- Epilog for the man pages (see also)
- Auto-generated comments.
This commit is contained in:
Batuhan Taskaya 2022-05-05 21:17:37 +03:00 committed by GitHub
parent 76495cbdec
commit f9b5c2f696
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 280 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/README.md
View File

@ -279,7 +279,7 @@ Synopsis:
$ http [flags] [METHOD] URL [ITEM [ITEM]]
```
See also `http --help`.
See also `http --help` (and for systems where man pages are available, you can use `man http`).
### Examples

160
extras/man/http.1
View File

@ -1,3 +1,4 @@
.\" This file is auto-generated from the parser declaration in httpie/cli/definition.py by extras/scripts/generate_man_pages.py.
.TH http 1 "2022-03-08" "HTTPie 3.1.1.dev0" "HTTPie Manual"
.SH NAME
http
@ -6,7 +7,7 @@ http [METHOD] URL [REQUEST_ITEM ...]
.SH DESCRIPTION
HTTPie: modern, user-friendly command-line HTTP client for the API era. <https://httpie.io>
.SH Positional Arguments
.SH Positional arguments
These arguments come after any flags and in the order they are listed here.
Only URL is required.
@ -27,8 +28,8 @@ is some data to be sent, otherwise GET:
.IP "\fB\,URL\/\fR"
The request URL. Scheme defaults to \'http://\' if the URL
does not include one. (You can override this with:\fB\,--default-scheme\/\fR=http/https)
The request URL. Scheme defaults to \[aq]http://\[aq] if the URL
does not include one. (You can override this with: \fB\,--default-scheme\/\fR=http/https)
You can also use a shorthand for localhost
@ -43,44 +44,44 @@ You can also use a shorthand for localhost
Optional key-value pairs to be included in the request. The separator used
determines the type:
\':\' HTTP headers:
\[aq]:\[aq] HTTP headers:
Referer:https://httpie.io Cookie:foo=bar User-Agent:bacon/1.0
\'==\' URL parameters to be appended to the request URI:
\[aq]==\[aq] URL parameters to be appended to the request URI:
search==httpie
\'=\' Data fields to be serialized into a JSON object (with\fB\,--json\/\fR,\fB\,-j\/\fR)
or form data (with\fB\,--form\/\fR,\fB\,-f\/\fR):
\[aq]=\[aq] Data fields to be serialized into a JSON object (with \fB\,--json\/\fR, \fB\,-j\/\fR)
or form data (with \fB\,--form\/\fR, \fB\,-f\/\fR):
name=HTTPie language=Python description=\'CLI HTTP client\'
name=HTTPie language=Python description=\[aq]CLI HTTP client\[aq]
\':=\' Non-string JSON data fields (only with\fB\,--json\/\fR,\fB\,-j\/\fR):
\[aq]:=\[aq] Non-string JSON data fields (only with \fB\,--json\/\fR, \fB\,-j\/\fR):
awesome:=true amount:=42 colors:=\'["red", "green", "blue"]\'
awesome:=true amount:=42 colors:=\[aq][\[dq]red\[dq], \[dq]green\[dq], \[dq]blue\[dq]]\[aq]
\'@\' Form file fields (only with\fB\,--form\/\fR or\fB\,--multipart\/\fR):
\[aq]@\[aq] Form file fields (only with \fB\,--form\/\fR or \fB\,--multipart\/\fR):
cv@\~/Documents/CV.pdf
cv@\'\~/Documents/CV.pdf;type=application/pdf\'
cv@\(ti/Documents/CV.pdf
cv@\[aq]\(ti/Documents/CV.pdf;type=application/pdf\[aq]
\'=@\' A data field like \'=\', but takes a file path and embeds its content:
\[aq]=@\[aq] A data field like \[aq]=\[aq], but takes a file path and embeds its content:
essay=@Documents/essay.txt
\':=@\' A raw JSON field like \':=\', but takes a file path and embeds its content:
\[aq]:=@\[aq] A raw JSON field like \[aq]:=\[aq], but takes a file path and embeds its content:
package:=@./package.json
You can use a backslash to escape a colliding separator in the field name:
field-name-with\\:colon=value
field-name-with\e:colon=value
.PP
.SH Predefined Content Types
.SH Predefined content types
.IP "\fB\,--json\/\fR, \fB\,-j\/\fR"
@ -104,13 +105,13 @@ multipart/form-data request.
.IP "\fB\,--multipart\/\fR"
Similar to\fB\,--form\/\fR, but always sends a multipart/form-data request (i.e., even without files).
Similar to \fB\,--form\/\fR, but always sends a multipart/form-data request (i.e., even without files).
.IP "\fB\,--boundary\/\fR"
Specify a custom boundary string for multipart/form-data requests. Only has effect only together with\fB\,--form\/\fR.
Specify a custom boundary string for multipart/form-data requests. Only has effect only together with \fB\,--form\/\fR.
.IP "\fB\,--raw\/\fR"
@ -119,7 +120,7 @@ Specify a custom boundary string for multipart/form-data requests. Only has effe
This option allows you to pass raw request data without extra processing
(as opposed to the structured request items syntax):
$ http\fB\,--raw\/\fR=\'data\' pie.dev/post
$ http \fB\,--raw\/\fR=\[aq]data\[aq] pie.dev/post
You can achieve the same by piping the data via stdin:
@ -133,7 +134,7 @@ Or have HTTPie load the raw data from a file:
.PP
.SH Content Processing Options
.SH Content processing options
.IP "\fB\,--compress\/\fR, \fB\,-x\/\fR"
@ -146,39 +147,39 @@ negative. Compression can be forced by repeating the argument.
.PP
.SH Output Processing
.SH Output processing
.IP "\fB\,--pretty\/\fR"
Controls output processing. The value can be "none" to not prettify
the output (default for redirected output), "all" to apply both colors
and formatting (default for terminal output), "colors", or "format".
Controls output processing. The value can be \[dq]none\[dq] to not prettify
the output (default for redirected output), \[dq]all\[dq] to apply both colors
and formatting (default for terminal output), \[dq]colors\[dq], or \[dq]format\[dq].
.IP "\fB\,--style\/\fR, \fB\,-s\/\fR \fI\,STYLE\/\fR"
Output coloring style (default is "auto"). It can be one of:
Output coloring style (default is \[dq]auto\[dq]). It can be one of:
auto, pie, pie-dark, pie-light, solarized
For finding out all available styles in your system, try:
$ http\fB\,--style\/\fR
$ http \fB\,--style\/\fR
The "auto" style follows your terminal\'s ANSI color styles.
The \[dq]auto\[dq] style follows your terminal\[aq]s ANSI color styles.
For non-auto styles 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).
$TERM environment variable is set to \[dq]xterm-256color\[dq] or similar
(e.g., via `export TERM=xterm-256color\[aq] in your \(ti/.bashrc).
.IP "\fB\,--unsorted\/\fR"
Disables all sorting while formatting output. It is a shortcut for:
\fB\,--format-options\/\fR=headers.sort:false,json.sort_keys:false
\fB\,--format-options\/\fR=headers.sort:false,json.sort_keys:false
@ -187,7 +188,7 @@ Disables all sorting while formatting output. It is a shortcut for:
Re-enables all sorting options while formatting output. It is a shortcut for:
\fB\,--format-options\/\fR=headers.sort:true,json.sort_keys:true
\fB\,--format-options\/\fR=headers.sort:true,json.sort_keys:true
@ -196,8 +197,8 @@ Re-enables all sorting options while formatting output. It is a shortcut for:
Override the response encoding for terminal display purposes, e.g.:
\fB\,--response-charset\/\fR=utf8
\fB\,--response-charset\/\fR=big5
\fB\,--response-charset\/\fR=utf8
\fB\,--response-charset\/\fR=big5
@ -206,8 +207,8 @@ Override the response encoding for terminal display purposes, e.g.:
Override the response mime type for coloring and formatting for the terminal, e.g.:
\fB\,--response-mime\/\fR=application/json
\fB\,--response-mime\/\fR=text/xml
\fB\,--response-mime\/\fR=application/json
\fB\,--response-mime\/\fR=text/xml
@ -215,7 +216,7 @@ Override the response mime type for coloring and formatting for the terminal, e.
Controls output formatting. Only relevant when formatting is enabled
through (explicit or implied)\fB\,--pretty\/\fR=all or\fB\,--pretty\/\fR=format.
through (explicit or implied) \fB\,--pretty\/\fR=all or \fB\,--pretty\/\fR=format.
The following are the default options:
headers.sort:true
@ -229,26 +230,26 @@ You may use this option multiple times, as well as specify multiple
comma-separated options at the same time. For example, this modifies the
settings to disable the sorting of JSON keys, and sets the indent size to 2:
\fB\,--format-options\/\fR json.sort_keys:false,json.indent:2
\fB\,--format-options\/\fR json.sort_keys:false,json.indent:2
This is something you will typically put into your config file.
.PP
.SH Output Options
.SH Output options
.IP "\fB\,--print\/\fR, \fB\,-p\/\fR \fI\,WHAT\/\fR"
String specifying what the output should contain:
\'H\' request headers
\'B\' request body
\'h\' response headers
\'b\' response body
\'m\' response metadata
\[aq]H\[aq] request headers
\[aq]B\[aq] request body
\[aq]h\[aq] response headers
\[aq]b\[aq] response body
\[aq]m\[aq] response metadata
The default behaviour is \'hb\' (i.e., the response
The default behaviour is \[aq]hb\[aq] (i.e., the response
headers and body is printed), if standard output is not redirected.
If the output is piped to another program or to a file, then only the
response body is printed by default.
@ -258,34 +259,34 @@ response body is printed by default.
.IP "\fB\,--headers\/\fR, \fB\,-h\/\fR"
Print only the response headers. Shortcut for\fB\,--print\/\fR=h.
Print only the response headers. Shortcut for \fB\,--print\/\fR=h.
.IP "\fB\,--meta\/\fR, \fB\,-m\/\fR"
Print only the response metadata. Shortcut for\fB\,--print\/\fR=m.
Print only the response metadata. Shortcut for \fB\,--print\/\fR=m.
.IP "\fB\,--body\/\fR, \fB\,-b\/\fR"
Print only the response body. Shortcut for\fB\,--print\/\fR=b.
Print only the response body. Shortcut for \fB\,--print\/\fR=b.
.IP "\fB\,--verbose\/\fR, \fB\,-v\/\fR"
Verbose output. For the level one (with single \fB\,-v\/\fR`/\fB\,--verbose\/\fR`), print
Verbose output. For the level one (with single `\fB\,-v\/\fR`/`\fB\,--verbose\/\fR`), print
the whole request as well as the response. Also print any intermediary
requests/responses (such as redirects). For the second level and higher,
print these as well as the response metadata.
Level one is a shortcut for:\fB\,--all\/\fR\fB\,--print\/\fR=BHbh
Level two is a shortcut for:\fB\,--all\/\fR\fB\,--print\/\fR=BHbhm
Level one is a shortcut for: \fB\,--all\/\fR \fB\,--print\/\fR=BHbh
Level two is a shortcut for: \fB\,--all\/\fR \fB\,--print\/\fR=BHbhm
.IP "\fB\,--all\/\fR"
@ -293,23 +294,23 @@ Level two is a shortcut for:\fB\,--all\/\fR\fB\,--print\/\fR=BHbhm
By default, only the final request/response is shown. Use this flag to show
any intermediary requests/responses as well. Intermediary requests include
followed redirects (with\fB\,--follow\/\fR), the first unauthorized request when
Digest auth is used \fB\,--auth\/\fR=digest), etc.
followed redirects (with \fB\,--follow\/\fR), the first unauthorized request when
Digest auth is used (\fB\,--auth\/\fR=digest), etc.
.IP "\fB\,--stream\/\fR, \fB\,-S\/\fR"
Always stream the response body by line, i.e., behave like `tail\fB\,-f\/\fR\'.
Always stream the response body by line, i.e., behave like `tail \fB\,-f\/\fR\[aq].
Without\fB\,--stream\/\fR and with\fB\,--pretty\/\fR (either set or implied),
Without \fB\,--stream\/\fR and with \fB\,--pretty\/\fR (either set or implied),
HTTPie fetches the whole response before it outputs the processed data.
Set this option when you want to continuously display a prettified
long-lived response, such as one from the Twitter streaming API.
It is useful also without\fB\,--pretty\/\fR: It ensures that the output is flushed
It is useful also without \fB\,--pretty\/\fR: It ensures that the output is flushed
more often and in smaller chunks.
@ -317,7 +318,7 @@ more often and in smaller chunks.
.IP "\fB\,--output\/\fR, \fB\,-o\/\fR \fI\,FILE\/\fR"
Save output to FILE instead of stdout. If\fB\,--download\/\fR is also set, then only
Save output to FILE instead of stdout. If \fB\,--download\/\fR is also set, then only
the response body is saved to FILE. Other parts of the HTTP exchange are
printed to stderr.
@ -327,7 +328,7 @@ printed to stderr.
Do not print the response body to stdout. Rather, download it and store it
in a file. The filename is guessed unless specified with\fB\,--output\/\fR
in a file. The filename is guessed unless specified with \fB\,--output\/\fR
[filename]. This action is similar to the default behaviour of wget.
@ -335,7 +336,7 @@ in a file. The filename is guessed unless specified with\fB\,--output\/\fR
.IP "\fB\,--continue\/\fR, \fB\,-c\/\fR"
Resume an interrupted download. Note that the\fB\,--output\/\fR option needs to be
Resume an interrupted download. Note that the \fB\,--output\/\fR option needs to be
specified as well.
@ -345,8 +346,8 @@ specified as well.
Do not print to stdout or stderr, except for errors and warnings when provided once.
Provide twice to suppress warnings as well.
stdout is still redirected if\fB\,--output\/\fR is specified.
Flag doesn\'t affect behaviour of download beyond not printing to terminal.
stdout is still redirected if \fB\,--output\/\fR is specified.
Flag doesn\[aq]t affect behaviour of download beyond not printing to terminal.
@ -383,24 +384,24 @@ exchange.
For username/password based authentication mechanisms (e.g
basic auth or digest auth) if only the username is provided
\fB\,-a\/\fR username), HTTPie will prompt for the password.
(\fB\,-a\/\fR username), HTTPie will prompt for the password.
.IP "\fB\,--auth-type\/\fR, \fB\,-A\/\fR"
The authentication mechanism to be used. Defaults to "basic".
The authentication mechanism to be used. Defaults to \[dq]basic\[dq].
"basic": Basic HTTP auth
\[dq]basic\[dq]: Basic HTTP auth
"digest": Digest HTTP auth
\[dq]digest\[dq]: Digest HTTP auth
"bearer": Bearer HTTP Auth
\[dq]bearer\[dq]: Bearer HTTP Auth
For finding out all available authentication types in your system, try:
$ http\fB\,--auth-type\/\fR
$ http \fB\,--auth-type\/\fR
.IP "\fB\,--ignore-netrc\/\fR"
@ -413,7 +414,7 @@ Ignore credentials from .netrc.
.IP "\fB\,--offline\/\fR"
Build the request and print it but don\'t actually send it.
Build the request and print it but don\(gat actually send it.
.IP "\fB\,--proxy\/\fR \fI\,PROTOCOL:PROXY_URL\/\fR"
@ -435,7 +436,7 @@ Follow 30x Location redirects.
.IP "\fB\,--max-redirects\/\fR"
By default, requests have a limit of 30 redirects (works with\fB\,--follow\/\fR).
By default, requests have a limit of 30 redirects (works with \fB\,--follow\/\fR).
@ -466,7 +467,7 @@ exit with an error if the status indicates one.
When the server replies with a 4xx (Client Error) or 5xx (Server Error)
status code, HTTPie exits with 4 or 5 respectively. If the response is a
3xx (Redirect) and\fB\,--follow\/\fR hasn\'t been set, then the exit status is 3.
3xx (Redirect) and \fB\,--follow\/\fR hasn\[aq]t been set, then the exit status is 3.
Also an error message is written to stderr if stdout is redirected.
@ -488,8 +489,8 @@ Enable streaming via chunked transfer encoding. The Transfer-Encoding header is
.IP "\fB\,--verify\/\fR"
Set to "no" (or "false") to skip checking the host\'s SSL certificate.
Defaults to "yes" ("true"). You can also pass the path to a CA_BUNDLE file
Set to \[dq]no\[dq] (or \[dq]false\[dq]) to skip checking the host\[aq]s SSL certificate.
Defaults to \[dq]yes\[dq] (\[dq]true\[dq]). You can also pass the path to a CA_BUNDLE file
for private certs. (Or you can set the REQUESTS_CA_BUNDLE environment
variable instead.)
@ -521,14 +522,14 @@ ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20:ECDH+AESGCM:DH+AESGCM:ECDH+A
You can specify a local cert to use as client side SSL certificate.
This file may either contain both private key and certificate or you may
specify\fB\,--cert-key\/\fR separately.
specify \fB\,--cert-key\/\fR separately.
.IP "\fB\,--cert-key\/\fR"
The private key to use with SSL. Only needed if\fB\,--cert\/\fR is given and the
The private key to use with SSL. Only needed if \fB\,--cert\/\fR is given and the
certificate file does not contain the private key.
@ -536,9 +537,9 @@ certificate file does not contain the private key.
.IP "\fB\,--cert-key-pass\/\fR"
The passphrase to be used to with the given private key. Only needed if\fB\,--cert-key\/\fR
The passphrase to be used to with the given private key. Only needed if \fB\,--cert-key\/\fR
is given and the key file requires a passphrase.
If not provided, you\'ll be prompted interactively.
If not provided, you\(gall be prompted interactively.
.PP
@ -588,3 +589,10 @@ information useful for debugging HTTPie itself and for reporting bugs.
.PP
.SH SEE ALSO
For every \fB\,--OPTION\/\fR there is also a \fB\,--no-OPTION\/\fR that reverts OPTION
to its default value.
Suggestions and bug reports are greatly appreciated:
https://github.com/httpie/httpie/issues

12
extras/man/httpie.1
View File

@ -1,9 +1,9 @@
.\" This file is auto-generated from the parser declaration in httpie/manager/cli.py by extras/scripts/generate_man_pages.py.
.TH httpie 1 "2022-03-08" "HTTPie 3.1.1.dev0" "HTTPie Manual"
.SH NAME
httpie
.SH SYNOPSIS
httpie HOSTNAME SESSION_NAME_OR_PATH TARGET TARGET TARGET TARGET TARGET TARGET
httpie
.SH DESCRIPTION
Managing interface for the HTTPie itself. <https://httpie.io/docs#manager>
@ -12,11 +12,17 @@ Be aware that you might be looking for http/https commands for sending
HTTP requests. This command is only available for managing the HTTTPie
plugins and the configuration around it.
If you are looking for the man pages of http/https commands, try one of the following:
$ man http
$ man https
.SH httpie cli export-args
Export available options for the CLI
.IP "\fB\,-f\/\fR, \fB\,--format\/\fR"
Format to export in.
.PP
.SH httpie cli sessions upgrade

160
extras/man/https.1
View File

@ -1,3 +1,4 @@
.\" This file is auto-generated from the parser declaration in httpie/cli/definition.py by extras/scripts/generate_man_pages.py.
.TH https 1 "2022-03-08" "HTTPie 3.1.1.dev0" "HTTPie Manual"
.SH NAME
https
@ -6,7 +7,7 @@ https [METHOD] URL [REQUEST_ITEM ...]
.SH DESCRIPTION
HTTPie: modern, user-friendly command-line HTTP client for the API era. <https://httpie.io>
.SH Positional Arguments
.SH Positional arguments
These arguments come after any flags and in the order they are listed here.
Only URL is required.
@ -27,8 +28,8 @@ is some data to be sent, otherwise GET:
.IP "\fB\,URL\/\fR"
The request URL. Scheme defaults to \'http://\' if the URL
does not include one. (You can override this with:\fB\,--default-scheme\/\fR=http/https)
The request URL. Scheme defaults to \[aq]http://\[aq] if the URL
does not include one. (You can override this with: \fB\,--default-scheme\/\fR=http/https)
You can also use a shorthand for localhost
@ -43,44 +44,44 @@ You can also use a shorthand for localhost
Optional key-value pairs to be included in the request. The separator used
determines the type:
\':\' HTTP headers:
\[aq]:\[aq] HTTP headers:
Referer:https://httpie.io Cookie:foo=bar User-Agent:bacon/1.0
\'==\' URL parameters to be appended to the request URI:
\[aq]==\[aq] URL parameters to be appended to the request URI:
search==httpie
\'=\' Data fields to be serialized into a JSON object (with\fB\,--json\/\fR,\fB\,-j\/\fR)
or form data (with\fB\,--form\/\fR,\fB\,-f\/\fR):
\[aq]=\[aq] Data fields to be serialized into a JSON object (with \fB\,--json\/\fR, \fB\,-j\/\fR)
or form data (with \fB\,--form\/\fR, \fB\,-f\/\fR):
name=HTTPie language=Python description=\'CLI HTTP client\'
name=HTTPie language=Python description=\[aq]CLI HTTP client\[aq]
\':=\' Non-string JSON data fields (only with\fB\,--json\/\fR,\fB\,-j\/\fR):
\[aq]:=\[aq] Non-string JSON data fields (only with \fB\,--json\/\fR, \fB\,-j\/\fR):
awesome:=true amount:=42 colors:=\'["red", "green", "blue"]\'
awesome:=true amount:=42 colors:=\[aq][\[dq]red\[dq], \[dq]green\[dq], \[dq]blue\[dq]]\[aq]
\'@\' Form file fields (only with\fB\,--form\/\fR or\fB\,--multipart\/\fR):
\[aq]@\[aq] Form file fields (only with \fB\,--form\/\fR or \fB\,--multipart\/\fR):
cv@\~/Documents/CV.pdf
cv@\'\~/Documents/CV.pdf;type=application/pdf\'
cv@\(ti/Documents/CV.pdf
cv@\[aq]\(ti/Documents/CV.pdf;type=application/pdf\[aq]
\'=@\' A data field like \'=\', but takes a file path and embeds its content:
\[aq]=@\[aq] A data field like \[aq]=\[aq], but takes a file path and embeds its content:
essay=@Documents/essay.txt
\':=@\' A raw JSON field like \':=\', but takes a file path and embeds its content:
\[aq]:=@\[aq] A raw JSON field like \[aq]:=\[aq], but takes a file path and embeds its content:
package:=@./package.json
You can use a backslash to escape a colliding separator in the field name:
field-name-with\\:colon=value
field-name-with\e:colon=value
.PP
.SH Predefined Content Types
.SH Predefined content types
.IP "\fB\,--json\/\fR, \fB\,-j\/\fR"
@ -104,13 +105,13 @@ multipart/form-data request.
.IP "\fB\,--multipart\/\fR"
Similar to\fB\,--form\/\fR, but always sends a multipart/form-data request (i.e., even without files).
Similar to \fB\,--form\/\fR, but always sends a multipart/form-data request (i.e., even without files).
.IP "\fB\,--boundary\/\fR"
Specify a custom boundary string for multipart/form-data requests. Only has effect only together with\fB\,--form\/\fR.
Specify a custom boundary string for multipart/form-data requests. Only has effect only together with \fB\,--form\/\fR.
.IP "\fB\,--raw\/\fR"
@ -119,7 +120,7 @@ Specify a custom boundary string for multipart/form-data requests. Only has effe
This option allows you to pass raw request data without extra processing
(as opposed to the structured request items syntax):
$ http\fB\,--raw\/\fR=\'data\' pie.dev/post
$ http \fB\,--raw\/\fR=\[aq]data\[aq] pie.dev/post
You can achieve the same by piping the data via stdin:
@ -133,7 +134,7 @@ Or have HTTPie load the raw data from a file:
.PP
.SH Content Processing Options
.SH Content processing options
.IP "\fB\,--compress\/\fR, \fB\,-x\/\fR"
@ -146,39 +147,39 @@ negative. Compression can be forced by repeating the argument.
.PP
.SH Output Processing
.SH Output processing
.IP "\fB\,--pretty\/\fR"
Controls output processing. The value can be "none" to not prettify
the output (default for redirected output), "all" to apply both colors
and formatting (default for terminal output), "colors", or "format".
Controls output processing. The value can be \[dq]none\[dq] to not prettify
the output (default for redirected output), \[dq]all\[dq] to apply both colors
and formatting (default for terminal output), \[dq]colors\[dq], or \[dq]format\[dq].
.IP "\fB\,--style\/\fR, \fB\,-s\/\fR \fI\,STYLE\/\fR"
Output coloring style (default is "auto"). It can be one of:
Output coloring style (default is \[dq]auto\[dq]). It can be one of:
auto, pie, pie-dark, pie-light, solarized
For finding out all available styles in your system, try:
$ http\fB\,--style\/\fR
$ http \fB\,--style\/\fR
The "auto" style follows your terminal\'s ANSI color styles.
The \[dq]auto\[dq] style follows your terminal\[aq]s ANSI color styles.
For non-auto styles 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).
$TERM environment variable is set to \[dq]xterm-256color\[dq] or similar
(e.g., via `export TERM=xterm-256color\[aq] in your \(ti/.bashrc).
.IP "\fB\,--unsorted\/\fR"
Disables all sorting while formatting output. It is a shortcut for:
\fB\,--format-options\/\fR=headers.sort:false,json.sort_keys:false
\fB\,--format-options\/\fR=headers.sort:false,json.sort_keys:false
@ -187,7 +188,7 @@ Disables all sorting while formatting output. It is a shortcut for:
Re-enables all sorting options while formatting output. It is a shortcut for:
\fB\,--format-options\/\fR=headers.sort:true,json.sort_keys:true
\fB\,--format-options\/\fR=headers.sort:true,json.sort_keys:true
@ -196,8 +197,8 @@ Re-enables all sorting options while formatting output. It is a shortcut for:
Override the response encoding for terminal display purposes, e.g.:
\fB\,--response-charset\/\fR=utf8
\fB\,--response-charset\/\fR=big5
\fB\,--response-charset\/\fR=utf8
\fB\,--response-charset\/\fR=big5
@ -206,8 +207,8 @@ Override the response encoding for terminal display purposes, e.g.:
Override the response mime type for coloring and formatting for the terminal, e.g.:
\fB\,--response-mime\/\fR=application/json
\fB\,--response-mime\/\fR=text/xml
\fB\,--response-mime\/\fR=application/json
\fB\,--response-mime\/\fR=text/xml
@ -215,7 +216,7 @@ Override the response mime type for coloring and formatting for the terminal, e.
Controls output formatting. Only relevant when formatting is enabled
through (explicit or implied)\fB\,--pretty\/\fR=all or\fB\,--pretty\/\fR=format.
through (explicit or implied) \fB\,--pretty\/\fR=all or \fB\,--pretty\/\fR=format.
The following are the default options:
headers.sort:true
@ -229,26 +230,26 @@ You may use this option multiple times, as well as specify multiple
comma-separated options at the same time. For example, this modifies the
settings to disable the sorting of JSON keys, and sets the indent size to 2:
\fB\,--format-options\/\fR json.sort_keys:false,json.indent:2
\fB\,--format-options\/\fR json.sort_keys:false,json.indent:2
This is something you will typically put into your config file.
.PP
.SH Output Options
.SH Output options
.IP "\fB\,--print\/\fR, \fB\,-p\/\fR \fI\,WHAT\/\fR"
String specifying what the output should contain:
\'H\' request headers
\'B\' request body
\'h\' response headers
\'b\' response body
\'m\' response metadata
\[aq]H\[aq] request headers
\[aq]B\[aq] request body
\[aq]h\[aq] response headers
\[aq]b\[aq] response body
\[aq]m\[aq] response metadata
The default behaviour is \'hb\' (i.e., the response
The default behaviour is \[aq]hb\[aq] (i.e., the response
headers and body is printed), if standard output is not redirected.
If the output is piped to another program or to a file, then only the
response body is printed by default.
@ -258,34 +259,34 @@ response body is printed by default.
.IP "\fB\,--headers\/\fR, \fB\,-h\/\fR"
Print only the response headers. Shortcut for\fB\,--print\/\fR=h.
Print only the response headers. Shortcut for \fB\,--print\/\fR=h.
.IP "\fB\,--meta\/\fR, \fB\,-m\/\fR"
Print only the response metadata. Shortcut for\fB\,--print\/\fR=m.
Print only the response metadata. Shortcut for \fB\,--print\/\fR=m.
.IP "\fB\,--body\/\fR, \fB\,-b\/\fR"
Print only the response body. Shortcut for\fB\,--print\/\fR=b.
Print only the response body. Shortcut for \fB\,--print\/\fR=b.
.IP "\fB\,--verbose\/\fR, \fB\,-v\/\fR"
Verbose output. For the level one (with single \fB\,-v\/\fR`/\fB\,--verbose\/\fR`), print
Verbose output. For the level one (with single `\fB\,-v\/\fR`/`\fB\,--verbose\/\fR`), print
the whole request as well as the response. Also print any intermediary
requests/responses (such as redirects). For the second level and higher,
print these as well as the response metadata.
Level one is a shortcut for:\fB\,--all\/\fR\fB\,--print\/\fR=BHbh
Level two is a shortcut for:\fB\,--all\/\fR\fB\,--print\/\fR=BHbhm
Level one is a shortcut for: \fB\,--all\/\fR \fB\,--print\/\fR=BHbh
Level two is a shortcut for: \fB\,--all\/\fR \fB\,--print\/\fR=BHbhm
.IP "\fB\,--all\/\fR"
@ -293,23 +294,23 @@ Level two is a shortcut for:\fB\,--all\/\fR\fB\,--print\/\fR=BHbhm
By default, only the final request/response is shown. Use this flag to show
any intermediary requests/responses as well. Intermediary requests include
followed redirects (with\fB\,--follow\/\fR), the first unauthorized request when
Digest auth is used \fB\,--auth\/\fR=digest), etc.
followed redirects (with \fB\,--follow\/\fR), the first unauthorized request when
Digest auth is used (\fB\,--auth\/\fR=digest), etc.
.IP "\fB\,--stream\/\fR, \fB\,-S\/\fR"
Always stream the response body by line, i.e., behave like `tail\fB\,-f\/\fR\'.
Always stream the response body by line, i.e., behave like `tail \fB\,-f\/\fR\[aq].
Without\fB\,--stream\/\fR and with\fB\,--pretty\/\fR (either set or implied),
Without \fB\,--stream\/\fR and with \fB\,--pretty\/\fR (either set or implied),
HTTPie fetches the whole response before it outputs the processed data.
Set this option when you want to continuously display a prettified
long-lived response, such as one from the Twitter streaming API.
It is useful also without\fB\,--pretty\/\fR: It ensures that the output is flushed
It is useful also without \fB\,--pretty\/\fR: It ensures that the output is flushed
more often and in smaller chunks.
@ -317,7 +318,7 @@ more often and in smaller chunks.
.IP "\fB\,--output\/\fR, \fB\,-o\/\fR \fI\,FILE\/\fR"
Save output to FILE instead of stdout. If\fB\,--download\/\fR is also set, then only
Save output to FILE instead of stdout. If \fB\,--download\/\fR is also set, then only
the response body is saved to FILE. Other parts of the HTTP exchange are
printed to stderr.
@ -327,7 +328,7 @@ printed to stderr.
Do not print the response body to stdout. Rather, download it and store it
in a file. The filename is guessed unless specified with\fB\,--output\/\fR
in a file. The filename is guessed unless specified with \fB\,--output\/\fR
[filename]. This action is similar to the default behaviour of wget.
@ -335,7 +336,7 @@ in a file. The filename is guessed unless specified with\fB\,--output\/\fR
.IP "\fB\,--continue\/\fR, \fB\,-c\/\fR"
Resume an interrupted download. Note that the\fB\,--output\/\fR option needs to be
Resume an interrupted download. Note that the \fB\,--output\/\fR option needs to be
specified as well.
@ -345,8 +346,8 @@ specified as well.
Do not print to stdout or stderr, except for errors and warnings when provided once.
Provide twice to suppress warnings as well.
stdout is still redirected if\fB\,--output\/\fR is specified.
Flag doesn\'t affect behaviour of download beyond not printing to terminal.
stdout is still redirected if \fB\,--output\/\fR is specified.
Flag doesn\[aq]t affect behaviour of download beyond not printing to terminal.
@ -383,24 +384,24 @@ exchange.
For username/password based authentication mechanisms (e.g
basic auth or digest auth) if only the username is provided
\fB\,-a\/\fR username), HTTPie will prompt for the password.
(\fB\,-a\/\fR username), HTTPie will prompt for the password.
.IP "\fB\,--auth-type\/\fR, \fB\,-A\/\fR"
The authentication mechanism to be used. Defaults to "basic".
The authentication mechanism to be used. Defaults to \[dq]basic\[dq].
"basic": Basic HTTP auth
\[dq]basic\[dq]: Basic HTTP auth
"digest": Digest HTTP auth
\[dq]digest\[dq]: Digest HTTP auth
"bearer": Bearer HTTP Auth
\[dq]bearer\[dq]: Bearer HTTP Auth
For finding out all available authentication types in your system, try:
$ http\fB\,--auth-type\/\fR
$ http \fB\,--auth-type\/\fR
.IP "\fB\,--ignore-netrc\/\fR"
@ -413,7 +414,7 @@ Ignore credentials from .netrc.
.IP "\fB\,--offline\/\fR"
Build the request and print it but don\'t actually send it.
Build the request and print it but don\(gat actually send it.
.IP "\fB\,--proxy\/\fR \fI\,PROTOCOL:PROXY_URL\/\fR"
@ -435,7 +436,7 @@ Follow 30x Location redirects.
.IP "\fB\,--max-redirects\/\fR"
By default, requests have a limit of 30 redirects (works with\fB\,--follow\/\fR).
By default, requests have a limit of 30 redirects (works with \fB\,--follow\/\fR).
@ -466,7 +467,7 @@ exit with an error if the status indicates one.
When the server replies with a 4xx (Client Error) or 5xx (Server Error)
status code, HTTPie exits with 4 or 5 respectively. If the response is a
3xx (Redirect) and\fB\,--follow\/\fR hasn\'t been set, then the exit status is 3.
3xx (Redirect) and \fB\,--follow\/\fR hasn\[aq]t been set, then the exit status is 3.
Also an error message is written to stderr if stdout is redirected.
@ -488,8 +489,8 @@ Enable streaming via chunked transfer encoding. The Transfer-Encoding header is
.IP "\fB\,--verify\/\fR"
Set to "no" (or "false") to skip checking the host\'s SSL certificate.
Defaults to "yes" ("true"). You can also pass the path to a CA_BUNDLE file
Set to \[dq]no\[dq] (or \[dq]false\[dq]) to skip checking the host\[aq]s SSL certificate.
Defaults to \[dq]yes\[dq] (\[dq]true\[dq]). You can also pass the path to a CA_BUNDLE file
for private certs. (Or you can set the REQUESTS_CA_BUNDLE environment
variable instead.)
@ -521,14 +522,14 @@ ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20:ECDH+AESGCM:DH+AESGCM:ECDH+A
You can specify a local cert to use as client side SSL certificate.
This file may either contain both private key and certificate or you may
specify\fB\,--cert-key\/\fR separately.
specify \fB\,--cert-key\/\fR separately.
.IP "\fB\,--cert-key\/\fR"
The private key to use with SSL. Only needed if\fB\,--cert\/\fR is given and the
The private key to use with SSL. Only needed if \fB\,--cert\/\fR is given and the
certificate file does not contain the private key.
@ -536,9 +537,9 @@ certificate file does not contain the private key.
.IP "\fB\,--cert-key-pass\/\fR"
The passphrase to be used to with the given private key. Only needed if\fB\,--cert-key\/\fR
The passphrase to be used to with the given private key. Only needed if \fB\,--cert-key\/\fR
is given and the key file requires a passphrase.
If not provided, you\'ll be prompted interactively.
If not provided, you\(gall be prompted interactively.
.PP
@ -588,3 +589,10 @@ information useful for debugging HTTPie itself and for reporting bugs.
.PP
.SH SEE ALSO
For every \fB\,--OPTION\/\fR there is also a \fB\,--no-OPTION\/\fR that reverts OPTION
to its default value.
Suggestions and bug reports are greatly appreciated:
https://github.com/httpie/httpie/issues

63
extras/scripts/generate_man_pages.py
View File

@ -14,16 +14,19 @@ from httpie.utils import split
# Escape certain characters so they are rendered properly on
# all terminals.
# https://man7.org/linux/man-pages/man7/groff_char.7.html
ESCAPE_MAP = {
"'": "\\'",
'~': '\\~',
'’': "\\'",
'\\': '\\\\',
'"': '\[dq]',
"'": '\[aq]',
'~': '\(ti',
'’': "\(ga",
'\\': '\e',
}
ESCAPE_MAP = {ord(key): value for key, value in ESCAPE_MAP.items()}
EXTRAS_DIR = Path(__file__).parent.parent
MAN_PAGE_PATH = EXTRAS_DIR / 'man'
PROJECT_ROOT = EXTRAS_DIR.parent
OPTION_HIGHLIGHT_RE = re.compile(
OptionsHighlighter.highlights[0]
@ -57,6 +60,18 @@ class ManPageBuilder:
def separate(self) -> None:
self.source.append('.PP')
def format_desc(self, desc: str) -> str:
description = _escape_and_dedent(desc)
description = OPTION_HIGHLIGHT_RE.sub(
# Boldify the option part, but don't remove the prefix (start of the match).
lambda match: match[1] + self.boldify(match['option']),
description
)
return description
def add_comment(self, comment: str) -> None:
self.source.append(f'.\\" {comment}')
def add_options(self, options: Iterable[str], *, metavar: Optional[str] = None) -> None:
text = ", ".join(map(self.boldify, options))
if metavar:
@ -92,8 +107,13 @@ def _escape_and_dedent(text: str) -> str:
return '\n'.join(lines).translate(ESCAPE_MAP)
def to_man_page(program_name: str, spec: ParserSpec) -> str:
def to_man_page(program_name: str, spec: ParserSpec, *, is_top_level_cmd: bool = False) -> str:
builder = ManPageBuilder()
builder.add_comment(
f"This file is auto-generated from the parser declaration "
+ (f"in {Path(spec.source_file).relative_to(PROJECT_ROOT)} " if spec.source_file else "")
+ f"by {Path(__file__).relative_to(PROJECT_ROOT)}."
)
builder.title_line(
full_name='HTTPie',
@ -104,10 +124,19 @@ def to_man_page(program_name: str, spec: ParserSpec) -> str:
builder.set_name(program_name)
with builder.section('SYNOPSIS'):
builder.write(render_as_string(to_usage(spec, program_name=program_name)))
# `http` and `https` are commands that can be directly used, so they can have
# have a valid usage. But `httpie` is a top-level command with multiple sub commands,
# so for the synopsis we'll only reference the `httpie` name.
if is_top_level_cmd:
synopsis = program_name
else:
synopsis = render_as_string(to_usage(spec, program_name=program_name))
builder.write(synopsis)
with builder.section('DESCRIPTION'):
builder.write(spec.description)
if spec.man_page_hint:
builder.write(spec.man_page_hint)
for index, group in enumerate(spec.groups, 1):
with builder.section(group.name):
@ -127,28 +156,26 @@ def to_man_page(program_name: str, spec: ParserSpec) -> str:
metavar = None
builder.add_options(raw_arg['options'], metavar=metavar)
description = _escape_and_dedent(raw_arg.get('description', ''))
description = OPTION_HIGHLIGHT_RE.sub(
lambda match: builder.boldify(match['option']),
description
)
builder.write('\n' + description + '\n')
desc = builder.format_desc(raw_arg.get('description', ''))
builder.write('\n' + desc + '\n')
builder.separate()
if spec.epilog:
with builder.section('SEE ALSO'):
builder.write(builder.format_desc(spec.epilog))
return builder.build()
def main() -> None:
for program_name, spec in [
('http', core_options),
('https', core_options),
('httpie', manager_options),
for program_name, spec, config in [
('http', core_options, {}),
('https', core_options, {}),
('httpie', manager_options, {'is_top_level_cmd': True}),
]:
with open((MAN_PAGE_PATH / program_name).with_suffix('.1'), 'w') as stream:
stream.write(to_man_page(program_name, spec))
stream.write(to_man_page(program_name, spec, **config))

5
httpie/cli/definition.py
View File

@ -26,16 +26,13 @@ options = ParserSpec(
'http',
description=f'{__doc__.strip()} <https://httpie.io>',
epilog="""
To learn more, you can try:
-> running 'http --manual'
-> visiting our full documentation at https://httpie.io/docs/cli
For every --OPTION there is also a --no-OPTION that reverts OPTION
to its default value.
Suggestions and bug reports are greatly appreciated:
https://github.com/httpie/httpie/issues
""",
source_file=__file__
)

18
httpie/cli/options.py
View File

@ -35,17 +35,6 @@ def drop_keys(
}
def _get_first_line(source: str) -> str:
parts = []
for line in source.strip().splitlines():
line = line.strip()
parts.append(line)
if line.endswith("."):
break
return " ".join(parts)
PARSER_SPEC_VERSION = '0.0.1a0'
@ -55,6 +44,8 @@ class ParserSpec:
description: Optional[str] = None
epilog: Optional[str] = None
groups: List['Group'] = field(default_factory=list)
man_page_hint: Optional[str] = None
source_file: Optional[str] = None
def finalize(self) -> 'ParserSpec':
if self.description:
@ -248,10 +239,11 @@ def to_data(abstract_options: ParserSpec) -> Dict[str, Any]:
return {'version': PARSER_SPEC_VERSION, 'spec': abstract_options.serialize()}
def parser_to_parser_spec(parser: argparse.ArgumentParser) -> ParserSpec:
def parser_to_parser_spec(parser: argparse.ArgumentParser, **kwargs) -> ParserSpec:
"""Take an existing argparse parser, and create a spec from it."""
return ParserSpec(
program=parser.prog,
description=parser.description,
epilog=parser.epilog
epilog=parser.epilog,
**kwargs
)

10
httpie/manager/cli.py
View File

@ -20,6 +20,7 @@ COMMANDS = {
{
'flags': ['-f', '--format'],
'choices': ['json'],
'help': 'Format to export in.',
'default': 'json'
}
],
@ -166,5 +167,12 @@ parser.add_argument(
'''
)
options = parser_to_parser_spec(parser)
man_page_hint = '''
If you are looking for the man pages of http/https commands, try one of the following:
$ man http
$ man https
'''
options = parser_to_parser_spec(parser, man_page_hint=man_page_hint, source_file=__file__)
generate_subparsers(parser, parser, COMMANDS, options)

32
httpie/output/ui/man_pages.py
View File

@ -7,6 +7,13 @@ from httpie.context import Environment
MAN_COMMAND = 'man'
NO_MAN_PAGES = os.getenv('HTTPIE_NO_MAN_PAGES', False)
# On some systems, HTTP(n) might exist but we are only
# interested in HTTP(1).
#
# For more information on man page sections: https://unix.stackexchange.com/a/138643
MAN_PAGE_SECTION = '1'
def is_available(program: str) -> bool:
"""Check whether HTTPie's man pages are available in this system."""
@ -14,18 +21,27 @@ def is_available(program: str) -> bool:
if NO_MAN_PAGES or os.system == 'nt':
return False
process = subprocess.run(
[MAN_COMMAND, program],
shell=False,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
return process.returncode == 0
try:
process = subprocess.run(
[MAN_COMMAND, MAN_PAGE_SECTION, program],
shell=False,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL
)
except Exception:
# There might be some errors outside of the process, e.g
# a permission error to execute something that is not an
# executable.
return False
else:
return process.returncode == 0
def display_for(env: Environment, program: str) -> None:
"""Display the man page for the given command (http/https)."""
subprocess.run(
[MAN_COMMAND, program], stdout=env.stdout, stderr=env.stderr
[MAN_COMMAND, MAN_PAGE_SECTION, program],
stdout=env.stdout,
stderr=env.stderr
)

11
httpie/output/ui/rich_help.py
View File

@ -26,6 +26,7 @@ STYLE_BOLD = 'bold'
MAX_CHOICE_CHARS = 80
LEFT_PADDING_2 = (0, 0, 0, 2)
LEFT_PADDING_3 = (0, 0, 0, 3)
LEFT_PADDING_4 = (0, 0, 0, 4)
LEFT_PADDING_5 = (0, 0, 0, 4)
@ -33,6 +34,12 @@ LEFT_INDENT_2 = (1, 0, 0, 2)
LEFT_INDENT_3 = (1, 0, 0, 3)
LEFT_INDENT_BOTTOM_3 = (0, 0, 1, 3)
MORE_INFO_COMMANDS = """
To learn more, you can try:
-> running 'http --manual'
-> visiting our full documentation at https://httpie.io/docs/cli
"""
class OptionsHighlighter(RegexHighlighter):
highlights = [
@ -213,6 +220,10 @@ def to_help_message(
Text('More Information', style=STYLE_SWITCH),
LEFT_INDENT_2,
)
yield Padding(
MORE_INFO_COMMANDS.rstrip('\n'),
LEFT_PADDING_3
)
yield Padding(
spec.epilog.rstrip('\n'),
LEFT_INDENT_BOTTOM_3,

2
httpie/output/ui/rich_palette.py
View File

@ -42,7 +42,7 @@ class _GenericColorCaster(dict):
return super().get(self._translate(key))
def _make_rich_color_theme(style_name: Optional[str]) -> 'Theme':
def _make_rich_color_theme(style_name: Optional[str] = None) -> 'Theme':
from rich.style import Style
from rich.theme import Theme

4
httpie/output/ui/rich_utils.py
View File

@ -6,13 +6,15 @@ from contextlib import contextmanager
from rich.console import Console, RenderableType
from rich.highlighter import Highlighter
from httpie.output.ui.rich_palette import _make_rich_color_theme
def render_as_string(renderable: RenderableType) -> str:
"""Render any `rich` object in a fake console and
return a *style-less* version of it as a string."""
with open(os.devnull, 'w') as null_stream:
fake_console = Console(file=null_stream, record=True)
fake_console = Console(file=null_stream, record=True, theme=_make_rich_color_theme())
fake_console.print(renderable)
return fake_console.export_text()

1
setup.py
View File

@ -116,5 +116,6 @@ setup(
data_files=[
('share/man/man1', ['extras/man/http.1']),
('share/man/man1', ['extras/man/https.1']),
('share/man/man1', ['extras/man/httpie.1']),
]
)