mirror of
https://github.com/httpie/cli.git
synced 2024-11-25 01:03:27 +01:00
Jakub Roztocil
parent
fc85988368
commit
70a78249c1
@ -6,8 +6,9 @@ This document records all notable changes to `HTTPie <https://httpie.org>`_.
|
||||
This project adheres to `Semantic Versioning <https://semver.org/>`_.
|
||||
|
||||
|
||||
`2.1.0-dev`_ (unreleased)
|
||||
-------------------------
|
||||
`2.1.0`_ (2020-04-18)
|
||||
---------------------
|
||||
|
||||
* Added ``--path-as-is`` to bypass dot segment (``/../`` or ``/./``)
|
||||
URL squashing (#895).
|
||||
* Changed the default value ``Accept`` header value for JSON requests from
|
||||
@ -420,4 +421,9 @@ This project adheres to `Semantic Versioning <https://semver.org/>`_.
|
||||
.. _1.0.2: https://github.com/jakubroztocil/httpie/compare/1.0.1...1.0.2
|
||||
.. _1.0.3: https://github.com/jakubroztocil/httpie/compare/1.0.2...1.0.3
|
||||
.. _2.0.0: https://github.com/jakubroztocil/httpie/compare/1.0.3...2.0.0
|
||||
.. _2.1.0-dev: https://github.com/jakubroztocil/httpie/compare/2.0.0...master
|
||||
.. _2.1.0: https://github.com/jakubroztocil/httpie/compare/2.0.0...2.1.0
|
||||
|
||||
|
||||
.. _#488:https://github.com/jakubroztocil/httpie/issues/488
|
||||
.. _#840:https://github.com/jakubroztocil/httpie/issues/840
|
||||
.. _#895:https://github.com/jakubroztocil/httpie/issues/895
|
||||
|
||||
119
README.rst
119
README.rst
@ -27,11 +27,20 @@ generally interacting with HTTP servers.
|
||||
.. section-numbering::
|
||||
|
||||
|
||||
About this document
|
||||
===================
|
||||
|
||||
This documentation is best viewed at `httpie.org/docs <https://httpie.org/docs>`_,
|
||||
where you can select your corresponding HTTPie version as well as run examples directly from the
|
||||
browser using a `termible.io <https://termible.io?utm_source=httpie-readme>`_ embedded terminal.
|
||||
If you are reading this on GitHub, then this text covers the current *development* version.
|
||||
You are invited to submit fixes and improvements to the the docs by editing
|
||||
`README.rst <https://github.com/jakubroztocil/httpie/blob/master/README.rst>`_.
|
||||
|
||||
|
||||
Main features
|
||||
=============
|
||||
|
||||
|
||||
* Expressive and intuitive syntax
|
||||
* Formatted and colorized terminal output
|
||||
* Built-in JSON support
|
||||
@ -157,13 +166,13 @@ Otherwise with ``pip``:
|
||||
|
||||
|
||||
Verify that now we have the
|
||||
`current development version identifier <https://github.com/jakubroztocil/httpie/blob/0af6ae1be444588bbc4747124e073423151178a0/httpie/__init__.py#L5>`_
|
||||
`current development version identifier <https://github.com/jakubroztocil/httpie/blob/master/httpie/__init__.py#L6>`_
|
||||
with the ``-dev`` suffix, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ http --version
|
||||
1.0.0-dev
|
||||
# 2.0.0-dev
|
||||
|
||||
|
||||
Usage
|
||||
@ -175,7 +184,7 @@ Hello World:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ http httpie.org
|
||||
$ http https://httpie.org/hello
|
||||
|
||||
|
||||
Synopsis:
|
||||
@ -307,7 +316,7 @@ If you find yourself manually constructing URLs with querystring parameters
|
||||
on the terminal, you may appreciate the ``param==value`` syntax for appending
|
||||
URL parameters.
|
||||
|
||||
With that, you don't have to worry about escaping the ``&``
|
||||
With that, you don’t have to worry about escaping the ``&``
|
||||
separators for your shell. Additionally, any special characters in the
|
||||
parameter name or value get automatically URL-escaped
|
||||
(as opposed to parameters specified in the full URL, which HTTPie doesn’t
|
||||
@ -459,14 +468,14 @@ their type is distinguished only by the separator used:
|
||||
+-----------------------+-----------------------------------------------------+
|
||||
|
||||
|
||||
Note that data fields aren't the only way to specify request data:
|
||||
Note that data fields aren’t the only way to specify request data:
|
||||
`Redirected input`_ is a mechanism for passing arbitrary request data.
|
||||
|
||||
|
||||
Escaping rules
|
||||
--------------
|
||||
|
||||
You can use ``\`` to escape characters that shouldn't be used as separators
|
||||
You can use ``\`` to escape characters that shouldn’t be used as separators
|
||||
(or parts thereof). For instance, ``foo\==bar`` will become a data key/value
|
||||
pair (``foo=`` and ``bar``) instead of a URL parameter.
|
||||
|
||||
@ -538,7 +547,7 @@ Explicit JSON
|
||||
|
||||
You can use ``--json, -j`` to explicitly set ``Accept``
|
||||
to ``application/json`` regardless of whether you are sending data
|
||||
(it's a shortcut for setting the header via the usual header notation:
|
||||
(it’s a shortcut for setting the header via the usual header notation:
|
||||
``http url Accept:'application/json, */*;q=0.5'``). Additionally,
|
||||
HTTPie will try to detect JSON responses even when the
|
||||
``Content-Type`` is incorrectly ``text/plain`` or unknown.
|
||||
@ -548,17 +557,20 @@ HTTPie will try to detect JSON responses even when the
|
||||
Non-string JSON fields
|
||||
----------------------
|
||||
|
||||
Non-string fields use the ``:=`` separator, which allows you to embed raw JSON
|
||||
into the resulting object. Text and raw JSON files can also be embedded into
|
||||
Non-string JSON fields use the ``:=`` separator, which allows you to embed arbitrary JSON data
|
||||
into the resulting JSON object. Additionally, text and raw JSON files can also be embedded into
|
||||
fields using ``=@`` and ``:=@``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ http PUT httpbin.org/put \
|
||||
name=John \
|
||||
age:=29 married:=false hobbies:='["http", "pies"]' \ # Raw JSON
|
||||
description=@about-john.txt \ # Embed text file
|
||||
bookmarks:=@bookmarks.json # Embed JSON file
|
||||
name=John \ # String (default)
|
||||
age:=29 \ # Raw JSON — Number
|
||||
married:=false \ # Raw JSON — Boolean
|
||||
hobbies:='["http", "pies"]' \ # Raw JSON — Array
|
||||
favorite:='{"tool": "HTTPie"}' \ # Raw JSON — Object
|
||||
bookmarks:=@files/data.json \ # Embed JSON file
|
||||
description=@files/text.txt # Embed text file
|
||||
|
||||
|
||||
.. code-block:: http
|
||||
@ -577,19 +589,33 @@ fields using ``=@`` and ``:=@``:
|
||||
"description": "John is a nice guy who likes pies.",
|
||||
"married": false,
|
||||
"name": "John",
|
||||
"favorite": {
|
||||
"tool": "HTTPie"
|
||||
},
|
||||
"bookmarks": {
|
||||
"HTTPie": "https://httpie.org",
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Please note that with this syntax the command gets unwieldy when sending
|
||||
complex data. In that case it's always better to use `redirected input`_:
|
||||
Raw and complex JSON
|
||||
--------------------
|
||||
|
||||
Please note that with the `request items`_ data field syntax, commands
|
||||
can quickly become unwieldy when sending complex structures.
|
||||
In such cases, it’s better to pass the full raw JSON data via
|
||||
`redirected input`_, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ echo '{"hello": "world"}' | http POST httpbin.org/post
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ http POST httpbin.org/post < files/data.json
|
||||
|
||||
Furthermore, this syntax only allows you to send an object as the JSON document, but not an array, etc.
|
||||
Here, again, the solution is to use `redirected input`_.
|
||||
|
||||
Forms
|
||||
=====
|
||||
@ -805,7 +831,7 @@ Send multiple cookies
|
||||
User-Agent: HTTPie/0.9.9
|
||||
|
||||
|
||||
If you often deal with cookies in your requests, then chances are you'd appreciate
|
||||
If you often deal with cookies in your requests, then chances are you’d appreciate
|
||||
the `sessions`_ feature.
|
||||
|
||||
|
||||
@ -818,7 +844,7 @@ The currently supported authentication schemes are Basic and Digest
|
||||
=================== ======================================================
|
||||
``--auth, -a`` Pass a ``username:password`` pair as
|
||||
the argument. Or, if you only specify a username
|
||||
(``-a username``), you'll be prompted for
|
||||
(``-a username``), you’ll be prompted for
|
||||
the password before the request is sent.
|
||||
To send an empty password, pass ``username:``.
|
||||
The ``username:password@hostname`` URL syntax is
|
||||
@ -855,7 +881,15 @@ Password prompt
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ http -a username example.org
|
||||
$ http -a username httpbin.org/basic-auth/username/password
|
||||
|
||||
|
||||
Empty password
|
||||
--------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ http -a username: httpbin.org/headers
|
||||
|
||||
|
||||
``.netrc``
|
||||
@ -893,7 +927,7 @@ Auth plugins
|
||||
|
||||
Additional authentication mechanism can be installed as plugins.
|
||||
They can be found on the `Python Package Index <https://pypi.python.org/pypi?%3Aaction=search&term=httpie&submit=search>`_.
|
||||
Here's a few picks:
|
||||
Here’s a few picks:
|
||||
|
||||
* `httpie-api-auth <https://github.com/pd/httpie-api-auth>`_: ApiAuth
|
||||
* `httpie-aws-auth <https://github.com/httpie/httpie-aws-auth>`_: AWS / Amazon S3
|
||||
@ -954,7 +988,7 @@ To change the default limit of maximum ``30`` redirects, use the
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ http --follow --all --max-redirects=5 httpbin.org/redirect/3
|
||||
$ http --follow --all --max-redirects=2 httpbin.org/redirect/3
|
||||
|
||||
|
||||
Proxies
|
||||
@ -996,7 +1030,7 @@ SOCKS
|
||||
-----
|
||||
|
||||
Homebrew-installed HTTPie comes with SOCKS proxy support out of the box.
|
||||
To enable SOCKS proxy support for non-Homebrew installations, you'll
|
||||
To enable SOCKS proxy support for non-Homebrew installations, you’ll
|
||||
might need to install ``requests[socks]`` manually using ``pip``:
|
||||
|
||||
|
||||
@ -1018,7 +1052,7 @@ HTTPS
|
||||
Server SSL certificate verification
|
||||
-----------------------------------
|
||||
|
||||
To skip the host's SSL certificate verification, you can pass ``--verify=no``
|
||||
To skip the host’s SSL certificate verification, you can pass ``--verify=no``
|
||||
(default is ``yes``):
|
||||
|
||||
.. code-block:: bash
|
||||
@ -1154,7 +1188,7 @@ authentication is used (``--auth=digest``), etc.
|
||||
|
||||
|
||||
The intermediary requests/response are by default formatted according to
|
||||
``--print, -p`` (and its shortcuts described above). If you'd like to change
|
||||
``--print, -p`` (and its shortcuts described above). If you’d like to change
|
||||
that, use the ``--history-print, -P`` option. It takes the same
|
||||
arguments as ``--print, -p`` but applies to the intermediary requests only.
|
||||
|
||||
@ -1169,10 +1203,10 @@ Conditional body download
|
||||
-------------------------
|
||||
|
||||
As an optimization, the response body is downloaded from the server
|
||||
only if it's part of the output. This is similar to performing a ``HEAD``
|
||||
only if it’s part of the output. This is similar to performing a ``HEAD``
|
||||
request, except that it applies to any HTTP method you use.
|
||||
|
||||
Let's say that there is an API that returns the whole resource when it is
|
||||
Let’s say that there is an API that returns the whole resource when it is
|
||||
updated, but you are only interested in the response headers to see the
|
||||
status code after an update:
|
||||
|
||||
@ -1183,8 +1217,8 @@ status code after an update:
|
||||
|
||||
Since we are only printing the HTTP headers here, the connection to the server
|
||||
is closed as soon as all the response headers have been received.
|
||||
Therefore, bandwidth and time isn't wasted downloading the body
|
||||
which you don't care about. The response headers are downloaded always,
|
||||
Therefore, bandwidth and time isn’t wasted downloading the body
|
||||
which you don’t care about. The response headers are downloaded always,
|
||||
even if they are not part of the output
|
||||
|
||||
|
||||
@ -1296,8 +1330,16 @@ Colors and formatting
|
||||
|
||||
Syntax highlighting is applied to HTTP headers and bodies (where it makes
|
||||
sense). You can choose your preferred color scheme via the ``--style`` option
|
||||
if you don't like the default one (see ``$ http --help`` for the possible
|
||||
values).
|
||||
if you don’t like the default one. There dozens of styles available, here are just a few special or notable ones:
|
||||
|
||||
==================== ========================================================================
|
||||
``auto`` Follows your terminal ANSI color styles. This is the default style used by HTTPie.
|
||||
``default`` Default styles of the underlying Pygments library. Not actually used by default by HTTPie.
|
||||
You can enable it with ``--style=default``
|
||||
``monokai`` A popular color scheme. Enable with ``--style=monokai``.
|
||||
``fruity`` A bold, colorful scheme. Enable with ``--style=fruity``.
|
||||
… See ``$ http --help`` for all the possible ``--style`` values.
|
||||
==================== ========================================================================
|
||||
|
||||
Also, the following formatting is applied:
|
||||
|
||||
@ -1347,11 +1389,11 @@ Redirected output
|
||||
HTTPie uses a different set of defaults for redirected output than for
|
||||
`terminal output`_. The differences being:
|
||||
|
||||
* Formatting and colors aren't applied (unless ``--pretty`` is specified).
|
||||
* Formatting and colors aren’t applied (unless ``--pretty`` is specified).
|
||||
* Only the response body is printed (unless one of the `output options`_ is set).
|
||||
* Also, binary data isn't suppressed.
|
||||
* Also, binary data isn’t suppressed.
|
||||
|
||||
The reason is to make piping HTTPie's output to another programs and
|
||||
The reason is to make piping HTTPie’s output to another programs and
|
||||
downloading files work with no extra flags. Most of the time, only the raw
|
||||
response body is of an interest when the output is redirected.
|
||||
|
||||
@ -1453,7 +1495,7 @@ Resuming downloads
|
||||
|
||||
If ``--output, -o`` is specified, you can resume a partial download using the
|
||||
``--continue, -c`` option. This only works with servers that support
|
||||
``Range`` requests and ``206 Partial Content`` responses. If the server doesn't
|
||||
``Range`` requests and ``206 Partial Content`` responses. If the server doesn’t
|
||||
support that, the whole file will simply be downloaded:
|
||||
|
||||
.. code-block:: bash
|
||||
@ -1468,7 +1510,7 @@ Other notes
|
||||
* ``--download`` always implies ``--follow`` (redirects are followed).
|
||||
* ``--download`` also implies ``--check-status``
|
||||
(error HTTP status will result in a non-zero exist static code).
|
||||
* HTTPie exits with status code ``1`` (error) if the body hasn't been fully
|
||||
* HTTPie exits with status code ``1`` (error) if the body hasn’t been fully
|
||||
downloaded.
|
||||
* ``Accept-Encoding`` cannot be set with ``--download``.
|
||||
|
||||
@ -1541,7 +1583,6 @@ to the same host.
|
||||
# Inspect / edit the generated session file:
|
||||
$ cat session.json
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Re-use the existing session — the API-Token header will be set:
|
||||
@ -1747,7 +1788,7 @@ What happens is that when HTTPie is invoked for example from a cron job,
|
||||
``stdin`` is not connected to a terminal.
|
||||
Therefore, rules for `redirected input`_ apply, i.e., HTTPie starts to read it
|
||||
expecting that the request body will be passed through.
|
||||
And since there's no data nor ``EOF``, it will be stuck. So unless you're
|
||||
And since there’s no data nor ``EOF``, it will be stuck. So unless you’re
|
||||
piping some data to HTTPie, this flag should be used in scripts.
|
||||
|
||||
Also, it might be good to set a connection ``--timeout`` limit to prevent
|
||||
@ -1762,7 +1803,7 @@ Interface design
|
||||
----------------
|
||||
|
||||
The syntax of the command arguments closely corresponds to the actual HTTP
|
||||
requests sent over the wire. It has the advantage that it's easy to remember
|
||||
requests sent over the wire. It has the advantage that it’s easy to remember
|
||||
and read. It is often possible to translate an HTTP request to an HTTPie
|
||||
argument list just by inlining the request elements. For example, compare this
|
||||
HTTP request:
|
||||
@ -1791,7 +1832,7 @@ with the HTTPie command that sends it:
|
||||
|
||||
Notice that both the order of elements and the syntax is very similar,
|
||||
and that only a small portion of the command is used to control HTTPie and
|
||||
doesn't directly correspond to any part of the request (here it's only ``-f``
|
||||
doesn’t directly correspond to any part of the request (here it’s only ``-f``
|
||||
asking HTTPie to send a form request).
|
||||
|
||||
The two modes, ``--pretty=all`` (default for terminal) and ``--pretty=none``
|
||||
|
||||
@ -3,6 +3,6 @@ HTTPie - a CLI, cURL-like tool for humans.
|
||||
|
||||
"""
|
||||
|
||||
__version__ = '2.1.0-dev'
|
||||
__version__ = '2.1.0'
|
||||
__author__ = 'Jakub Roztocil'
|
||||
__licence__ = 'BSD'
|
||||
|
||||
35
setup.py
35
setup.py
@ -10,8 +10,11 @@ import httpie
|
||||
|
||||
|
||||
class PyTest(TestCommand):
|
||||
# `$ python setup.py test' simply installs minimal requirements
|
||||
# and runs the tests with no fancy stuff like parallel execution.
|
||||
"""
|
||||
Running `$ python setup.py test' simply installs minimal requirements
|
||||
and runs the tests with no fancy stuff like parallel execution.
|
||||
|
||||
"""
|
||||
def finalize_options(self):
|
||||
TestCommand.finalize_options(self)
|
||||
self.test_args = [
|
||||
@ -26,8 +29,6 @@ class PyTest(TestCommand):
|
||||
|
||||
|
||||
tests_require = [
|
||||
# Pytest needs to come last.
|
||||
# https://bitbucket.org/pypa/setuptools/issue/196/
|
||||
'pytest-httpbin',
|
||||
'pytest',
|
||||
'mock',
|
||||
@ -38,28 +39,24 @@ install_requires = [
|
||||
'requests>=2.22.0',
|
||||
'Pygments>=2.5.2',
|
||||
]
|
||||
|
||||
install_requires_win_only = [
|
||||
'colorama>=0.2.4',
|
||||
]
|
||||
|
||||
# Conditional dependencies:
|
||||
|
||||
# sdist
|
||||
if 'bdist_wheel' not in sys.argv:
|
||||
try:
|
||||
# noinspection PyUnresolvedReferences
|
||||
import argparse
|
||||
except ImportError:
|
||||
install_requires.append('argparse>=1.2.1')
|
||||
|
||||
if 'win32' in str(sys.platform).lower():
|
||||
# Terminal colors for Windows
|
||||
install_requires.append('colorama>=0.2.4')
|
||||
install_requires.extend(install_requires_win_only)
|
||||
|
||||
|
||||
# bdist_wheel
|
||||
extras_require = {
|
||||
# https://wheel.readthedocs.io/en/latest/#defining-conditional-dependencies
|
||||
'python_version == "3.0" or python_version == "3.1"': ['argparse>=1.2.1'],
|
||||
':sys_platform == "win32"': ['colorama>=0.2.4'],
|
||||
':sys_platform == "win32"': install_requires_win_only,
|
||||
}
|
||||
|
||||
|
||||
@ -74,7 +71,7 @@ setup(
|
||||
description=httpie.__doc__.strip(),
|
||||
long_description=long_description(),
|
||||
url='https://httpie.org/',
|
||||
download_url='https://github.com/jakubroztocil/httpie',
|
||||
download_url=f'https://github.com/jakubroztocil/httpie/archive/{httpie.__version__}.tar.gz',
|
||||
author=httpie.__author__,
|
||||
author_email='jakub@roztocil.co',
|
||||
license=httpie.__licence__,
|
||||
@ -85,6 +82,7 @@ setup(
|
||||
'https = httpie.__main__:main',
|
||||
],
|
||||
},
|
||||
python_requires='>=3.6',
|
||||
extras_require=extras_require,
|
||||
install_requires=install_requires,
|
||||
tests_require=tests_require,
|
||||
@ -93,8 +91,6 @@ setup(
|
||||
'Development Status :: 5 - Production/Stable',
|
||||
'Programming Language :: Python',
|
||||
'Programming Language :: Python :: 3 :: Only',
|
||||
'Programming Language :: Python :: 3.6',
|
||||
'Programming Language :: Python :: 3.7',
|
||||
'Environment :: Console',
|
||||
'Intended Audience :: Developers',
|
||||
'Intended Audience :: System Administrators',
|
||||
@ -106,4 +102,11 @@ setup(
|
||||
'Topic :: Text Processing',
|
||||
'Topic :: Utilities'
|
||||
],
|
||||
project_urls={
|
||||
'Documentation': 'https://httpie.org/docs',
|
||||
'Source': 'https://github.com/jakubroztocil/httpie',
|
||||
'Online Demo': 'https://httpie.org/run',
|
||||
'Donate': 'https://httpie.org/donate',
|
||||
'Twitter': 'https://twitter.com/clihttp',
|
||||
},
|
||||
)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user