extern/httpie-cli
1
0
Fork 1
mirror of https://github.com/httpie/cli.git synced 2025-02-17 01:50:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

v0.2.6

Browse Source
This commit is contained in:
Jakub Roztocil 2012-07-26 09:01:30 +02:00
parent f45cc0eec0
commit b53d483163
2 changed files with 138 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

243
README.rst
View File

@ -1,36 +1,33 @@
=======================
HTTPie: cURL for humans HTTPie: cURL for humans
======================= =======================
`☞ README for stable version <https://github.com/jkbr/httpie/tree/0.2.5#readme>`_
**HTTPie is a CLI HTTP utility** built out of frustration with existing tools. **HTTPie is a CLI HTTP utility** built out of frustration with existing tools.
The goal is to make CLI interaction with HTTP-based services as Its goal is to make CLI interaction with HTTP-based services as
human-friendly as possible. **human-friendly** as possible. HTTPie provides an ``http`` command that allows
for issuing **arbitrary HTTP** requests using a **simple and natural syntax**,
HTTPie does so by providing an ``http`` command that allows for issuing and displays **colorized responses**:
arbitrary HTTP requests using a **simple and natural syntax** and displaying
**colorized responses**:
.. image:: https://github.com/jkbr/httpie/raw/master/httpie.png .. image:: https://github.com/jkbr/httpie/raw/master/httpie.png
:alt: HTTPie compared to cURL :alt: HTTPie compared to cURL
Under the hood, HTTPie uses the excellent HTTPie supports Python 2.6+ (including Python 3.x and PyPy) and has been tested
`Requests <http://python-requests.org>`_ and under Mac OS X, Linux and Windows. It also has a
`Pygments <http://pygments.org/>`_ Python libraries. Python 2.6+ is supported comprehensive `suite of tests`_ with `continuous integration`_.
(including 3.x).
Under the hood, the excellent `Requests`_ and `Pygments`_ Python libraries
are used.
Installation Installation
------------ ============
The latest **stable version** of HTTPie can always be installed The latest **stable version** of HTTPie can always be installed or updated
(or updated to) via to via `pip`_ (prefered)
`pip <http://www.pip-installer.org/en/latest/index.html>`_:: or ``easy_install``::
pip install -U httpie pip install -U httpie
# easy_install pip
You can also use `easy_install` (``pip`` is prefered, though)::
easy_install httpie
Or, you can install the **development version** directly from GitHub: Or, you can install the **development version** directly from GitHub:
@ -42,15 +39,12 @@ Or, you can install the **development version** directly from GitHub:
pip install -U https://github.com/jkbr/httpie/tarball/master pip install -U https://github.com/jkbr/httpie/tarball/master
There are also packages available for `Ubuntu`_, `Debian`_ and possibly other
There are packages available for distributions as well.
`Ubuntu <http://packages.ubuntu.com/httpie>`_,
`Debian <http://packages.debian.org/httpie>`_ and
possibly other major distros as well.
Usage Usage
----- =====
Hello world:: Hello world::
@ -60,40 +54,53 @@ Synopsis::
http [flags] [METHOD] URL [items] http [flags] [METHOD] URL [items]
There are five types of key-value pair items available: There are five different types of key/value pair ``items`` available:
Headers (``Name:Value``) +-----------------------+-----------------------------------------------------+
Arbitrary HTTP headers. The ``:`` character is used to separate a header's | **Headers** | Arbitrary HTTP headers. The ``:`` character is |
name from its value, e.g., ``X-API-Token:123``. | ``Name:Value`` | used to separate a header's name from its value, |
| | e.g., ``X-API-Token:123``. |
+-----------------------+-----------------------------------------------------+
| **Simple data | Included in the request body and depending on the |
| fields** | ``Content-Type`` they are automatically serialized |
| ``field=value`` | as a JSON ``Object`` (default) or |
| | ``application/x-www-form-urlencoded`` |
| | (``--form``/ ``-f``). Data items use ``=`` |
| | as the separator, e.g., ``hello=world``. |
+-----------------------+-----------------------------------------------------+
| **Raw JSON fields** | Useful when the ``Content-Type`` is JSON and one or |
| ``field:=json`` | more fields need to be a ``Boolean``, ``Number``, |
| | nested ``Object``, or an ``Array``. It's because |
| | simple data items are always serialized as a |
| | ``String``. E.g., ``pies:=[1,2,3]``, or |
| | ``'meals:=["ham","spam"]'`` (note the quotes). |
| | It may be more convenient to pass the whole JSON |
| | body via ``stdin`` when it's more complex |
| | (see examples bellow). |
+-----------------------+-----------------------------------------------------+
| **File fields** | Only available with ``-f`` / ``--form``. Use ``@`` |
| ``field@/dir/file`` | as the separator, e.g., |
| | ``screenshot@~/Pictures/img.png``. |
| | The presence of a file field results |
| | into a ``multipart/form-data`` request. |
+-----------------------+-----------------------------------------------------+
| **Query string | Appends the given name/value pair as a query |
| parameters** | string parameter to the URL. |
| ``name==value`` | The ``==`` separator is used |
+-----------------------+-----------------------------------------------------+
Simple data fields (``field=value``)
Data items are included in the request body. Depending on the
``Content-Type``, they are automatically serialized as a JSON ``Object``
(default) or ``application/x-www-form-urlencoded`` (the ``-f`` flag).
Data items use ``=`` as the separator, e.g., ``hello=world``.
Raw JSON fields (``field:=value``) All ``items`` come after the URL, and, unlike ``flags``, they become part of
This item type is needed when ``Content-Type`` is JSON and a field's value the actual request being is sent. Their types are distinguished by the
is a ``Boolean``, ``Number``, nested ``Object`` or an ``Array``, because separator used.
simple data items are always serialized as ``String``.
E.g. ``pies:=[1,2,3]``, or ``'meals=["ham", "spam"]'`` (mind the quotes).
File fields (``field@/path/to/file``)
Only available with ``-f`` / ``--form``. Use ``@`` as the separator, e.g.,
``screenshot@/path/to/file.png``. The presence of a file field results into
a ``multipart/form-data`` request.
Query string parameters (``name==value``)
Appends the given name/value pair as a query string parameter to the URL.
Examples Examples
^^^^^^^^ --------
:: ::
http PATCH api.example.com/person/1 X-API-Token:123 name=John email=john@example.org age:=29 http PATCH api.example.com/person/1 X-API-Token:123 name=John email=john@example.org age:=29
The following request is issued:: The following request is issued::
PATCH /person/1 HTTP/1.1 PATCH /person/1 HTTP/1.1
@ -103,7 +110,6 @@ The following request is issued::
{"name": "John", "email": "john@example.org", "age": 29} {"name": "John", "email": "john@example.org", "age": 29}
It can easily be changed to a **form** request using the ``-f`` It can easily be changed to a **form** request using the ``-f``
(or ``--form``) flag, which produces:: (or ``--form``) flag, which produces::
@ -120,21 +126,21 @@ simulate a **file upload form** submission. It is done using the
http -f POST example.com/jobs name=John cv@~/Documents/cv.pdf http -f POST example.com/jobs name=John cv@~/Documents/cv.pdf
The above will send the same request as if the following HTML form were submitted:: The above will send the same request as if the following HTML form were
submitted::
<form enctype="multipart/form-data" method="post" action="http://example.com/jobs"> <form enctype="multipart/form-data" method="post" action="http://example.com/jobs">
<input type="text" name="name" /> <input type="text" name="name" />
<input type="file" name="cv" /> <input type="file" name="cv" />
</form> </form>
**Query string parameters** can be added to any request without having to quote **Query string parameters** can be added to any request without having to
the ``&`` characters:: escape the ``&`` characters. The following request will contain
``?search=donuts&in=fridge`` as the query string part of the URL::
http GET example.com/ search==donuts in==fridge http GET example.com search==donuts in==fridge
Will ``GET`` the URL ``http://example.com/?search=donuts&in=fridge``. The whole request body can also be passed in **via stdin,** in which
A whole request body can be passed in via **``stdin``** instead, in which
case it will be used with no further processing:: case it will be used with no further processing::
echo '{"name": "John"}' | http PATCH example.com/person/1 X-API-Token:123 echo '{"name": "John"}' | http PATCH example.com/person/1 X-API-Token:123
@ -147,29 +153,28 @@ That can be used for **piping services together**. The following example
http GET https://api.github.com/repos/jkbr/httpie | http POST httpbin.org/post http GET https://api.github.com/repos/jkbr/httpie | http POST httpbin.org/post
The above can be further simplified by omitting ``GET`` and ``POST`` because The above can be further simplified by omitting ``GET`` and ``POST`` because
they are both default here. The first command has no request data, whereas they are both default here as the first command has no request data whereas
the second one does via ``stdin``:: the second one has via ``stdin``::
http https://api.github.com/repos/jkbr/httpie | http httpbin.org/post http https://api.github.com/repos/jkbr/httpie | http httpbin.org/post
Note that when the **output is redirected** (like the examples above), HTTPie Note that when the **output is redirected** (like the examples above), HTTPie
applies a different set of defaults then for console output. Namely colors applies a different set of defaults than for a console output. Namely, colors
aren't used (can be forced with ``--pretty``) and only the response body aren't used (unless ``--pretty`` is set) and only the response body
gets printed (can be overwritten with ``--print``). is printed (unless ``--print`` options specified).
An alternative to ``stdin`` is to pass a file name whose content will be used An alternative to ``stdin`` is to pass a filename whose content will be used
as the request body. It has the advantage that the ``Content-Type`` header as the request body. It has the advantage that the ``Content-Type`` header
will automatically be set to the appropriate value based on the filename will automatically be set to the appropriate value based on the filename
extension (using the ``mimetypes`` module). Therefore, the following will extension. Thus, the following will request will send the verbatim contents
request will send the verbatim contents of the file with of the file with ``Content-Type: application/xml``::
``Content-Type: application/xml``::
http PUT httpbin.org/put @/data/file.xml http PUT httpbin.org/put @/data/file.xml
When using HTTPie from **shell scripts**, you might want to use the When using HTTPie from **shell scripts** it can be useful to use the
``--check-status`` flag. It instructs HTTPie to exit with an error if the ``--check-status`` flag. It instructs HTTPie to exit with an error if the
HTTP status is one of ``3xx``, ``4xx``, or ``5xx``. The exit status will HTTP status is one of ``3xx``, ``4xx``, or ``5xx``. The exit status will
be ``3`` (unless ``--allow-redirects`` is set), ``4``, or ``5`` be ``3`` (unless ``--allow-redirects`` is set), ``4``, or ``5``,
respectively:: respectively::
#!/bin/bash #!/bin/bash
@ -187,12 +192,10 @@ respectively::
Flags Flags
^^^^^ -----
Most of the flags mirror the arguments understood by ``requests.request``.
See ``http --help`` for more details::
``$ http --help``::
$ http --help
usage: http [--help] [--version] [--json | --form] [--traceback] usage: http [--help] [--version] [--json | --form] [--traceback]
[--pretty | --ugly] [--pretty | --ugly]
[--print OUTPUT_OPTIONS | --verbose | --headers | --body] [--print OUTPUT_OPTIONS | --verbose | --headers | --body]
@ -288,34 +291,30 @@ See ``http --help`` for more details::
--timeout TIMEOUT Float describes the timeout of the request (Use --timeout TIMEOUT Float describes the timeout of the request (Use
socket.setdefaulttimeout() as fallback). socket.setdefaulttimeout() as fallback).
Contribute Contribute
---------- ==========
`View contributors on GitHub <https://github.com/jkbr/httpie/contributors>`_. Bug reports and code and documentation patches are greatly appretiated. You can
also help by using the development version of HTTPie and reporting any bugs you
might encounter.
If you have found a bug or have a feature request, the Before working on a new feature or a bug, please browse the `existing issues`_
`issue tracker <https://github.com/jkbr/httpie/issues?state=open>`_ is the to see whether it has been previously discussed.
place to start a discussion about it.
To contribute code or documentation, please first browse the existing issues Then fork and clone `the repository`_.
to see if the feature/bug has previously been discussed. Then fork
`the repository <https://github.com/jkbr/httpie>`_, make changes in your
develop branch and submit a pull request. Note: Pull requests with tests and
documentation are 53.6% more awesome :)
To point the ``http`` command to your working copy you can install HTTPie in To point the ``http`` command to your local branch during development you can
the editable mode:: install HTTPie in an editable mode::
pip install --editable . pip install --editable .
It's a good idea to run the existing suite of tests before a pull requests is To run the existing suite of tests before a pull request is submitted::
submitted::
python setup.py test python setup.py test
`Tox <http://tox.testrun.org/>`_ can used to conveniently run tests in all of `Tox`_ can also be used to conveniently run tests in all of the
the `supported Python environments`_::
`supported Python environments <https://github.com/jkbr/httpie/blob/master/tox.ini>`_::
# Install tox # Install tox
pip install tox pip install tox
@ -323,23 +322,25 @@ the
# Run tests # Run tests
tox tox
Changelog
---------
* `0.2.6dev <https://github.com/jkbr/httpie/compare/0.2.5...master>`_ Changelog
* Short option for ``--headers`` is now ``-h`` (``-t`` has been removed, =========
for usage use ``--help``).
* Form data and URL params can now have multiple fields with the same name * `0.2.7dev`_
* `0.2.6`_ (2012-07-26)
* The short option for ``--headers`` is now ``-h`` (``-t`` has been
removed, for usage use ``--help``).
* Form data and URL parameters can have multiple fields with the same name
(e.g.,``http -f url a=1 a=2``). (e.g.,``http -f url a=1 a=2``).
* Added ``--check-status`` to exit with an error for HTTP 3xx, 4xx and * Added ``--check-status`` to exit with an error on HTTP 3xx, 4xx and
5xx (3, 4, 5). 5xx (3, 4, and 5, respectively).
* If the output is piped to another program or redirected to a file, * If the output is piped to another program or redirected to a file,
the new default behaviour is to only print the response body. the default behaviour is to only print the response body.
(It can still be overwritten via the ``--print`` flag.) (It can still be overwritten via the ``--print`` flag.)
* Improved highlighting of HTTP headers. * Improved highlighting of HTTP headers.
* Added query string parameters (param==value). * Added query string parameters (``param==value``).
* Added support for terminal colors under Windows. * Added support for terminal colors under Windows.
* `0.2.5 <https://github.com/jkbr/httpie/compare/0.2.2...0.2.5>`_ (2012-07-17) * `0.2.5`_ (2012-07-17)
* Unicode characters in prettified JSON now don't get escaped for * Unicode characters in prettified JSON now don't get escaped for
improved readability. improved readability.
* --auth now prompts for a password if only a username provided. * --auth now prompts for a password if only a username provided.
@ -348,16 +349,16 @@ Changelog
* Fixed missing query string when displaying the request headers via * Fixed missing query string when displaying the request headers via
``--verbose``. ``--verbose``.
* Fixed Content-Type for requests with no data. * Fixed Content-Type for requests with no data.
* `0.2.2 <https://github.com/jkbr/httpie/compare/0.2.1...0.2.2>`_ (2012-06-24) * `0.2.2`_ (2012-06-24)
* The ``METHOD`` positional argument can now be omitted (defaults to * The ``METHOD`` positional argument can now be omitted (defaults to
``GET``, or to ``POST`` with data). ``GET``, or to ``POST`` with data).
* Fixed --verbose --form. * Fixed --verbose --form.
* Added support for `Tox <http://tox.testrun.org/>`_. * Added support for `Tox`_.
* `0.2.1 <https://github.com/jkbr/httpie/compare/0.2.0...0.2.1>`_ (2012-06-13) * `0.2.1`_ (2012-06-13)
* Added compatibility with ``requests-0.12.1``. * Added compatibility with ``requests-0.12.1``.
* Dropped custom JSON and HTTP lexers in favor of the ones newly included * Dropped custom JSON and HTTP lexers in favor of the ones newly included
in ``pygments-1.5``. in ``pygments-1.5``.
* `0.2.0 <https://github.com/jkbr/httpie/compare/0.1.6...0.2.0>`_ (2012-04-25) * `0.2.0`_ (2012-04-25)
* Added Python 3 support. * Added Python 3 support.
* Added the ability to print the HTTP request as well as the response * Added the ability to print the HTTP request as well as the response
(see ``--print`` and ``--verbose``). (see ``--print`` and ``--verbose``).
@ -367,4 +368,34 @@ Changelog
* Improved syntax highlighting for JSON. * Improved syntax highlighting for JSON.
* Added support for field name escaping. * Added support for field name escaping.
* Many bug fixes. * Many bug fixes.
* `0.1.6 <https://github.com/jkbr/httpie/compare/0.1.4...0.1.6>`_ (2012-03-04) * `0.1.6`_ (2012-03-04)
Authors
=======
`Jakub Roztocil`_ (`@jkbrzt`_) created HTTPie and
`these fine people <https://github.com/jkbr/httpie/contributors>`_
have contributed.
.. _suite of tests: https://github.com/jkbr/httpie/blob/master/tests/tests.py
.. _continuous integration: http://travis-ci.org/#!/jkbr/httpie
.. _Requests: http://python-requests.org
.. _Pygments: http://pygments.org/
.. _pip: http://www.pip-installer.org/en/latest/index.html
.. _Tox: http://tox.testrun.org
.. _supported Python environments: https://github.com/jkbr/httpie/blob/master/tox.ini
.. _Ubuntu: http://packages.ubuntu.com/httpie
.. _Debian: http://packages.debian.org/httpie
.. _the repository: https://github.com/jkbr/httpie
.. _Jakub Roztocil: http://roztocil.name
.. _@jkbrzt: https://twitter.com/jkbrzt
.. _existing issues: https://github.com/jkbr/httpie/issues?state=open
.. _0.1.6: https://github.com/jkbr/httpie/compare/0.1.4...0.1.6
.. _0.2.0: https://github.com/jkbr/httpie/compare/0.1.6...0.2.0
.. _0.2.1: https://github.com/jkbr/httpie/compare/0.2.0...0.2.1
.. _0.2.2: https://github.com/jkbr/httpie/compare/0.2.1...0.2.2
.. _0.2.5: https://github.com/jkbr/httpie/compare/0.2.2...0.2.5
.. _0.2.6: https://github.com/jkbr/httpie/compare/0.2.5...0.2.6
.. _0.2.7dev: https://github.com/jkbr/httpie/compare/0.2.6...master

2
httpie/__init__.py
View File

@ -3,5 +3,5 @@ HTTPie - cURL for humans.
""" """
__author__ = 'Jakub Roztocil' __author__ = 'Jakub Roztocil'
__version__ = '0.2.6dev' __version__ = '0.2.6'
__licence__ = 'BSD' __licence__ = 'BSD'