extern/httpie-cli
1
0
Fork 1
mirror of https://github.com/httpie/cli.git synced 2025-06-24 11:33:48 +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]] $ 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 ### Examples

100
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" .TH http 1 "2022-03-08" "HTTPie 3.1.1.dev0" "HTTPie Manual"
.SH NAME .SH NAME
http http
@ -6,7 +7,7 @@ http [METHOD] URL [REQUEST_ITEM ...]
.SH DESCRIPTION .SH DESCRIPTION
HTTPie: modern, user-friendly command-line HTTP client for the API era. <https://httpie.io> 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. These arguments come after any flags and in the order they are listed here.
Only URL is required. Only URL is required.
@ -27,7 +28,7 @@ is some data to be sent, otherwise GET:
.IP "\fB\,URL\/\fR" .IP "\fB\,URL\/\fR"
The request URL. Scheme defaults to \'http://\' if the URL 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) does not include one. (You can override this with: \fB\,--default-scheme\/\fR=http/https)
You can also use a shorthand for localhost 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 Optional key-value pairs to be included in the request. The separator used
determines the type: determines the type:
\':\' HTTP headers: \[aq]:\[aq] HTTP headers:
Referer:https://httpie.io Cookie:foo=bar User-Agent:bacon/1.0 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 search==httpie
\'=\' Data fields to be serialized into a JSON object (with\fB\,--json\/\fR,\fB\,-j\/\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): 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@\(ti/Documents/CV.pdf
cv@\'\~/Documents/CV.pdf;type=application/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 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 package:=@./package.json
You can use a backslash to escape a colliding separator in the field name: 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 .PP
.SH Predefined Content Types .SH Predefined content types
.IP "\fB\,--json\/\fR, \fB\,-j\/\fR" .IP "\fB\,--json\/\fR, \fB\,-j\/\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 This option allows you to pass raw request data without extra processing
(as opposed to the structured request items syntax): (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: 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 .PP
.SH Content Processing Options .SH Content processing options
.IP "\fB\,--compress\/\fR, \fB\,-x\/\fR" .IP "\fB\,--compress\/\fR, \fB\,-x\/\fR"
@ -146,20 +147,20 @@ negative. Compression can be forced by repeating the argument.
.PP .PP
.SH Output Processing .SH Output processing
.IP "\fB\,--pretty\/\fR" .IP "\fB\,--pretty\/\fR"
Controls output processing. The value can be "none" to not prettify Controls output processing. The value can be \[dq]none\[dq] to not prettify
the output (default for redirected output), "all" to apply both colors the output (default for redirected output), \[dq]all\[dq] to apply both colors
and formatting (default for terminal output), "colors", or "format". and formatting (default for terminal output), \[dq]colors\[dq], or \[dq]format\[dq].
.IP "\fB\,--style\/\fR, \fB\,-s\/\fR \fI\,STYLE\/\fR" .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 auto, pie, pie-dark, pie-light, solarized
@ -168,10 +169,10 @@ 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 For non-auto styles to work properly, please make sure that the
$TERM environment variable is set to "xterm-256color" or similar $TERM environment variable is set to \[dq]xterm-256color\[dq] or similar
(e.g., via `export TERM=xterm-256color\' in your \~/.bashrc). (e.g., via `export TERM=xterm-256color\[aq] in your \(ti/.bashrc).
.IP "\fB\,--unsorted\/\fR" .IP "\fB\,--unsorted\/\fR"
@ -236,19 +237,19 @@ This is something you will typically put into your config file.
.PP .PP
.SH Output Options .SH Output options
.IP "\fB\,--print\/\fR, \fB\,-p\/\fR \fI\,WHAT\/\fR" .IP "\fB\,--print\/\fR, \fB\,-p\/\fR \fI\,WHAT\/\fR"
String specifying what the output should contain: String specifying what the output should contain:
\'H\' request headers \[aq]H\[aq] request headers
\'B\' request body \[aq]B\[aq] request body
\'h\' response headers \[aq]h\[aq] response headers
\'b\' response body \[aq]b\[aq] response body
\'m\' response metadata \[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. 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 If the output is piped to another program or to a file, then only the
response body is printed by default. response body is printed by default.
@ -279,7 +280,7 @@ Print only the response body. Shortcut for\fB\,--print\/\fR=b.
.IP "\fB\,--verbose\/\fR, \fB\,-v\/\fR" .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 the whole request as well as the response. Also print any intermediary
requests/responses (such as redirects). For the second level and higher, requests/responses (such as redirects). For the second level and higher,
print these as well as the response metadata. print these as well as the response metadata.
@ -294,14 +295,14 @@ 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 By default, only the final request/response is shown. Use this flag to show
any intermediary requests/responses as well. Intermediary requests include any intermediary requests/responses as well. Intermediary requests include
followed redirects (with \fB\,--follow\/\fR), the first unauthorized request when followed redirects (with \fB\,--follow\/\fR), the first unauthorized request when
Digest auth is used \fB\,--auth\/\fR=digest), etc. Digest auth is used (\fB\,--auth\/\fR=digest), etc.
.IP "\fB\,--stream\/\fR, \fB\,-S\/\fR" .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. HTTPie fetches the whole response before it outputs the processed data.
@ -346,7 +347,7 @@ specified as well.
Do not print to stdout or stderr, except for errors and warnings when provided once. Do not print to stdout or stderr, except for errors and warnings when provided once.
Provide twice to suppress warnings as well. Provide twice to suppress warnings as well.
stdout is still redirected if \fB\,--output\/\fR is specified. stdout is still redirected if \fB\,--output\/\fR is specified.
Flag doesn\'t affect behaviour of download beyond not printing to terminal. Flag doesn\[aq]t affect behaviour of download beyond not printing to terminal.
@ -383,20 +384,20 @@ exchange.
For username/password based authentication mechanisms (e.g For username/password based authentication mechanisms (e.g
basic auth or digest auth) if only the username is provided 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" .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: For finding out all available authentication types in your system, try:
@ -413,7 +414,7 @@ Ignore credentials from .netrc.
.IP "\fB\,--offline\/\fR" .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" .IP "\fB\,--proxy\/\fR \fI\,PROTOCOL:PROXY_URL\/\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) 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 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. 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" .IP "\fB\,--verify\/\fR"
Set to "no" (or "false") to skip checking the host\'s SSL certificate. Set to \[dq]no\[dq] (or \[dq]false\[dq]) to skip checking the host\[aq]s SSL certificate.
Defaults to "yes" ("true"). You can also pass the path to a CA_BUNDLE file 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 for private certs. (Or you can set the REQUESTS_CA_BUNDLE environment
variable instead.) variable instead.)
@ -538,7 +539,7 @@ certificate file does not contain the private key.
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. 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 .PP
@ -588,3 +589,10 @@ information useful for debugging HTTPie itself and for reporting bugs.
.PP .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" .TH httpie 1 "2022-03-08" "HTTPie 3.1.1.dev0" "HTTPie Manual"
.SH NAME .SH NAME
httpie httpie
.SH SYNOPSIS .SH SYNOPSIS
httpie HOSTNAME SESSION_NAME_OR_PATH TARGET TARGET TARGET TARGET TARGET TARGET httpie
.SH DESCRIPTION .SH DESCRIPTION
Managing interface for the HTTPie itself. <https://httpie.io/docs#manager> 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 HTTP requests. This command is only available for managing the HTTTPie
plugins and the configuration around it. 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 .SH httpie cli export-args
Export available options for the CLI Export available options for the CLI
.IP "\fB\,-f\/\fR, \fB\,--format\/\fR" .IP "\fB\,-f\/\fR, \fB\,--format\/\fR"
Format to export in.
.PP .PP
.SH httpie cli sessions upgrade .SH httpie cli sessions upgrade

100
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" .TH https 1 "2022-03-08" "HTTPie 3.1.1.dev0" "HTTPie Manual"
.SH NAME .SH NAME
https https
@ -6,7 +7,7 @@ https [METHOD] URL [REQUEST_ITEM ...]
.SH DESCRIPTION .SH DESCRIPTION
HTTPie: modern, user-friendly command-line HTTP client for the API era. <https://httpie.io> 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. These arguments come after any flags and in the order they are listed here.
Only URL is required. Only URL is required.
@ -27,7 +28,7 @@ is some data to be sent, otherwise GET:
.IP "\fB\,URL\/\fR" .IP "\fB\,URL\/\fR"
The request URL. Scheme defaults to \'http://\' if the URL 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) does not include one. (You can override this with: \fB\,--default-scheme\/\fR=http/https)
You can also use a shorthand for localhost 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 Optional key-value pairs to be included in the request. The separator used
determines the type: determines the type:
\':\' HTTP headers: \[aq]:\[aq] HTTP headers:
Referer:https://httpie.io Cookie:foo=bar User-Agent:bacon/1.0 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 search==httpie
\'=\' Data fields to be serialized into a JSON object (with\fB\,--json\/\fR,\fB\,-j\/\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): 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@\(ti/Documents/CV.pdf
cv@\'\~/Documents/CV.pdf;type=application/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 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 package:=@./package.json
You can use a backslash to escape a colliding separator in the field name: 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 .PP
.SH Predefined Content Types .SH Predefined content types
.IP "\fB\,--json\/\fR, \fB\,-j\/\fR" .IP "\fB\,--json\/\fR, \fB\,-j\/\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 This option allows you to pass raw request data without extra processing
(as opposed to the structured request items syntax): (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: 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 .PP
.SH Content Processing Options .SH Content processing options
.IP "\fB\,--compress\/\fR, \fB\,-x\/\fR" .IP "\fB\,--compress\/\fR, \fB\,-x\/\fR"
@ -146,20 +147,20 @@ negative. Compression can be forced by repeating the argument.
.PP .PP
.SH Output Processing .SH Output processing
.IP "\fB\,--pretty\/\fR" .IP "\fB\,--pretty\/\fR"
Controls output processing. The value can be "none" to not prettify Controls output processing. The value can be \[dq]none\[dq] to not prettify
the output (default for redirected output), "all" to apply both colors the output (default for redirected output), \[dq]all\[dq] to apply both colors
and formatting (default for terminal output), "colors", or "format". and formatting (default for terminal output), \[dq]colors\[dq], or \[dq]format\[dq].
.IP "\fB\,--style\/\fR, \fB\,-s\/\fR \fI\,STYLE\/\fR" .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 auto, pie, pie-dark, pie-light, solarized
@ -168,10 +169,10 @@ 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 For non-auto styles to work properly, please make sure that the
$TERM environment variable is set to "xterm-256color" or similar $TERM environment variable is set to \[dq]xterm-256color\[dq] or similar
(e.g., via `export TERM=xterm-256color\' in your \~/.bashrc). (e.g., via `export TERM=xterm-256color\[aq] in your \(ti/.bashrc).
.IP "\fB\,--unsorted\/\fR" .IP "\fB\,--unsorted\/\fR"
@ -236,19 +237,19 @@ This is something you will typically put into your config file.
.PP .PP
.SH Output Options .SH Output options
.IP "\fB\,--print\/\fR, \fB\,-p\/\fR \fI\,WHAT\/\fR" .IP "\fB\,--print\/\fR, \fB\,-p\/\fR \fI\,WHAT\/\fR"
String specifying what the output should contain: String specifying what the output should contain:
\'H\' request headers \[aq]H\[aq] request headers
\'B\' request body \[aq]B\[aq] request body
\'h\' response headers \[aq]h\[aq] response headers
\'b\' response body \[aq]b\[aq] response body
\'m\' response metadata \[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. 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 If the output is piped to another program or to a file, then only the
response body is printed by default. response body is printed by default.
@ -279,7 +280,7 @@ Print only the response body. Shortcut for\fB\,--print\/\fR=b.
.IP "\fB\,--verbose\/\fR, \fB\,-v\/\fR" .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 the whole request as well as the response. Also print any intermediary
requests/responses (such as redirects). For the second level and higher, requests/responses (such as redirects). For the second level and higher,
print these as well as the response metadata. print these as well as the response metadata.
@ -294,14 +295,14 @@ 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 By default, only the final request/response is shown. Use this flag to show
any intermediary requests/responses as well. Intermediary requests include any intermediary requests/responses as well. Intermediary requests include
followed redirects (with \fB\,--follow\/\fR), the first unauthorized request when followed redirects (with \fB\,--follow\/\fR), the first unauthorized request when
Digest auth is used \fB\,--auth\/\fR=digest), etc. Digest auth is used (\fB\,--auth\/\fR=digest), etc.
.IP "\fB\,--stream\/\fR, \fB\,-S\/\fR" .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. HTTPie fetches the whole response before it outputs the processed data.
@ -346,7 +347,7 @@ specified as well.
Do not print to stdout or stderr, except for errors and warnings when provided once. Do not print to stdout or stderr, except for errors and warnings when provided once.
Provide twice to suppress warnings as well. Provide twice to suppress warnings as well.
stdout is still redirected if \fB\,--output\/\fR is specified. stdout is still redirected if \fB\,--output\/\fR is specified.
Flag doesn\'t affect behaviour of download beyond not printing to terminal. Flag doesn\[aq]t affect behaviour of download beyond not printing to terminal.
@ -383,20 +384,20 @@ exchange.
For username/password based authentication mechanisms (e.g For username/password based authentication mechanisms (e.g
basic auth or digest auth) if only the username is provided 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" .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: For finding out all available authentication types in your system, try:
@ -413,7 +414,7 @@ Ignore credentials from .netrc.
.IP "\fB\,--offline\/\fR" .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" .IP "\fB\,--proxy\/\fR \fI\,PROTOCOL:PROXY_URL\/\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) 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 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. 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" .IP "\fB\,--verify\/\fR"
Set to "no" (or "false") to skip checking the host\'s SSL certificate. Set to \[dq]no\[dq] (or \[dq]false\[dq]) to skip checking the host\[aq]s SSL certificate.
Defaults to "yes" ("true"). You can also pass the path to a CA_BUNDLE file 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 for private certs. (Or you can set the REQUESTS_CA_BUNDLE environment
variable instead.) variable instead.)
@ -538,7 +539,7 @@ certificate file does not contain the private key.
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. 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 .PP
@ -588,3 +589,10 @@ information useful for debugging HTTPie itself and for reporting bugs.
.PP .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 # Escape certain characters so they are rendered properly on
# all terminals. # all terminals.
# https://man7.org/linux/man-pages/man7/groff_char.7.html
ESCAPE_MAP = { ESCAPE_MAP = {
"'": "\\'", '"': '\[dq]',
'~': '\\~', "'": '\[aq]',
'’': "\\'", '~': '\(ti',
'\\': '\\\\', '’': "\(ga",
'\\': '\e',
} }
ESCAPE_MAP = {ord(key): value for key, value in ESCAPE_MAP.items()} ESCAPE_MAP = {ord(key): value for key, value in ESCAPE_MAP.items()}
EXTRAS_DIR = Path(__file__).parent.parent EXTRAS_DIR = Path(__file__).parent.parent
MAN_PAGE_PATH = EXTRAS_DIR / 'man' MAN_PAGE_PATH = EXTRAS_DIR / 'man'
PROJECT_ROOT = EXTRAS_DIR.parent
OPTION_HIGHLIGHT_RE = re.compile( OPTION_HIGHLIGHT_RE = re.compile(
OptionsHighlighter.highlights[0] OptionsHighlighter.highlights[0]
@ -57,6 +60,18 @@ class ManPageBuilder:
def separate(self) -> None: def separate(self) -> None:
self.source.append('.PP') 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: def add_options(self, options: Iterable[str], *, metavar: Optional[str] = None) -> None:
text = ", ".join(map(self.boldify, options)) text = ", ".join(map(self.boldify, options))
if metavar: if metavar:
@ -92,8 +107,13 @@ def _escape_and_dedent(text: str) -> str:
return '\n'.join(lines).translate(ESCAPE_MAP) 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 = 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( builder.title_line(
full_name='HTTPie', full_name='HTTPie',
@ -104,10 +124,19 @@ def to_man_page(program_name: str, spec: ParserSpec) -> str:
builder.set_name(program_name) builder.set_name(program_name)
with builder.section('SYNOPSIS'): 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'): with builder.section('DESCRIPTION'):
builder.write(spec.description) builder.write(spec.description)
if spec.man_page_hint:
builder.write(spec.man_page_hint)
for index, group in enumerate(spec.groups, 1): for index, group in enumerate(spec.groups, 1):
with builder.section(group.name): with builder.section(group.name):
@ -127,28 +156,26 @@ def to_man_page(program_name: str, spec: ParserSpec) -> str:
metavar = None metavar = None
builder.add_options(raw_arg['options'], metavar=metavar) builder.add_options(raw_arg['options'], metavar=metavar)
description = _escape_and_dedent(raw_arg.get('description', '')) desc = builder.format_desc(raw_arg.get('description', ''))
description = OPTION_HIGHLIGHT_RE.sub( builder.write('\n' + desc + '\n')
lambda match: builder.boldify(match['option']),
description
)
builder.write('\n' + description + '\n')
builder.separate() builder.separate()
if spec.epilog:
with builder.section('SEE ALSO'):
builder.write(builder.format_desc(spec.epilog))
return builder.build() return builder.build()
def main() -> None: def main() -> None:
for program_name, spec in [ for program_name, spec, config in [
('http', core_options), ('http', core_options, {}),
('https', core_options), ('https', core_options, {}),
('httpie', manager_options), ('httpie', manager_options, {'is_top_level_cmd': True}),
]: ]:
with open((MAN_PAGE_PATH / program_name).with_suffix('.1'), 'w') as stream: 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', 'http',
description=f'{__doc__.strip()} <https://httpie.io>', description=f'{__doc__.strip()} <https://httpie.io>',
epilog=""" 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 For every --OPTION there is also a --no-OPTION that reverts OPTION
to its default value. to its default value.
Suggestions and bug reports are greatly appreciated: Suggestions and bug reports are greatly appreciated:
https://github.com/httpie/httpie/issues 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' PARSER_SPEC_VERSION = '0.0.1a0'
@ -55,6 +44,8 @@ class ParserSpec:
description: Optional[str] = None description: Optional[str] = None
epilog: Optional[str] = None epilog: Optional[str] = None
groups: List['Group'] = field(default_factory=list) groups: List['Group'] = field(default_factory=list)
man_page_hint: Optional[str] = None
source_file: Optional[str] = None
def finalize(self) -> 'ParserSpec': def finalize(self) -> 'ParserSpec':
if self.description: 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()} 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.""" """Take an existing argparse parser, and create a spec from it."""
return ParserSpec( return ParserSpec(
program=parser.prog, program=parser.prog,
description=parser.description, 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'], 'flags': ['-f', '--format'],
'choices': ['json'], 'choices': ['json'],
'help': 'Format to export in.',
'default': 'json' '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) generate_subparsers(parser, parser, COMMANDS, options)

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

@ -7,6 +7,13 @@ from httpie.context import Environment
MAN_COMMAND = 'man' MAN_COMMAND = 'man'
NO_MAN_PAGES = os.getenv('HTTPIE_NO_MAN_PAGES', False) 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: def is_available(program: str) -> bool:
"""Check whether HTTPie's man pages are available in this system.""" """Check whether HTTPie's man pages are available in this system."""
@ -14,12 +21,19 @@ def is_available(program: str) -> bool:
if NO_MAN_PAGES or os.system == 'nt': if NO_MAN_PAGES or os.system == 'nt':
return False return False
try:
process = subprocess.run( process = subprocess.run(
[MAN_COMMAND, program], [MAN_COMMAND, MAN_PAGE_SECTION, program],
shell=False, shell=False,
stdout=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
stderr=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 return process.returncode == 0
@ -27,5 +41,7 @@ def display_for(env: Environment, program: str) -> None:
"""Display the man page for the given command (http/https).""" """Display the man page for the given command (http/https)."""
subprocess.run( 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 MAX_CHOICE_CHARS = 80
LEFT_PADDING_2 = (0, 0, 0, 2) LEFT_PADDING_2 = (0, 0, 0, 2)
LEFT_PADDING_3 = (0, 0, 0, 3)
LEFT_PADDING_4 = (0, 0, 0, 4) LEFT_PADDING_4 = (0, 0, 0, 4)
LEFT_PADDING_5 = (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_3 = (1, 0, 0, 3)
LEFT_INDENT_BOTTOM_3 = (0, 0, 1, 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): class OptionsHighlighter(RegexHighlighter):
highlights = [ highlights = [
@ -213,6 +220,10 @@ def to_help_message(
Text('More Information', style=STYLE_SWITCH), Text('More Information', style=STYLE_SWITCH),
LEFT_INDENT_2, LEFT_INDENT_2,
) )
yield Padding(
MORE_INFO_COMMANDS.rstrip('\n'),
LEFT_PADDING_3
)
yield Padding( yield Padding(
spec.epilog.rstrip('\n'), spec.epilog.rstrip('\n'),
LEFT_INDENT_BOTTOM_3, 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)) 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.style import Style
from rich.theme import Theme 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.console import Console, RenderableType
from rich.highlighter import Highlighter from rich.highlighter import Highlighter
from httpie.output.ui.rich_palette import _make_rich_color_theme
def render_as_string(renderable: RenderableType) -> str: def render_as_string(renderable: RenderableType) -> str:
"""Render any `rich` object in a fake console and """Render any `rich` object in a fake console and
return a *style-less* version of it as a string.""" return a *style-less* version of it as a string."""
with open(os.devnull, 'w') as null_stream: 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) fake_console.print(renderable)
return fake_console.export_text() return fake_console.export_text()

1
setup.py
View File

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