v0.2.6

httpie · Jul 26, 2012 · b53d483 · b53d483
1 parent f45cc0e
commit b53d483
Show file tree

Hide file tree

Showing 2 changed files with 140 additions and 109 deletions.
diff --git a/README.rst b/README.rst
@@ -1,36 +1,33 @@
+=======================
 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.
-The goal is to make CLI interaction with HTTP-based services as
-human-friendly as possible.
-
-HTTPie does so by providing an ``http`` command that allows for issuing
-arbitrary HTTP requests using a **simple and natural syntax** and displaying
-**colorized responses**:
+Its goal is to make CLI interaction with HTTP-based services as
+**human-friendly** as possible. HTTPie provides an ``http`` command that allows
+for issuing **arbitrary HTTP** requests using a **simple and natural syntax**,
+and displays **colorized responses**:
 
 .. image:: https://github.com/jkbr/httpie/raw/master/httpie.png
     :alt: HTTPie compared to cURL
 
-Under the hood, HTTPie uses the excellent
-`Requests <http://python-requests.org>`_ and
-`Pygments <http://pygments.org/>`_ Python libraries. Python 2.6+ is supported
-(including 3.x).
+HTTPie supports Python 2.6+ (including Python 3.x and PyPy) and has been tested
+under Mac OS X, Linux and Windows. It also has a
+comprehensive `suite of tests`_ with `continuous integration`_.
 
-Installation
-------------
+Under the hood, the excellent `Requests`_ and `Pygments`_ Python libraries
+are used.
 
-The latest **stable version** of HTTPie can always be installed
-(or updated to) via
-`pip <http://www.pip-installer.org/en/latest/index.html>`_::
 
-    pip install -U httpie
+Installation
+============
 
-You can also use `easy_install` (``pip`` is prefered, though)::
+The latest **stable version** of HTTPie can always be installed or updated
+to via `pip`_ (prefered)
+or ``easy_install``::
 
-    easy_install httpie
+    pip install -U httpie
+    # easy_install pip
 
 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
 
-
-There are packages available for
-`Ubuntu <http://packages.ubuntu.com/httpie>`_,
-`Debian <http://packages.debian.org/httpie>`_ and
-possibly other major distros as well.
+There are also packages available for `Ubuntu`_, `Debian`_ and possibly other
+distributions as well.
 
 
 Usage
------
+=====
 
 Hello world::
 
@@ -60,40 +54,53 @@ Synopsis::
 
     http [flags] [METHOD] URL [items]
 
-There are five types of key-value pair items available:
-
-Headers (``Name:Value``)
-   Arbitrary HTTP headers. The ``:`` character is used to separate a header's
-   name from its value, e.g., ``X-API-Token:123``.
-
-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``)
-  This item type is needed when ``Content-Type`` is JSON and a field's value
-  is a ``Boolean``, ``Number``,  nested ``Object`` or an ``Array``, because
-  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.
+There are five different types of key/value pair ``items`` available:
+
++-----------------------+-----------------------------------------------------+
+| **Headers**           | Arbitrary HTTP headers. The ``:`` character is      |
+| ``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                        |
++-----------------------+-----------------------------------------------------+
+
+
+All ``items`` come after the URL, and, unlike ``flags``, they become part of
+the actual request being is sent. Their types are distinguished by the
+separator used.
 
 
 Examples
-^^^^^^^^
+--------
 ::
 
     http PATCH api.example.com/person/1 X-API-Token:123 name=John email=john@example.org age:=29
 
-
 The following request is issued::
 
     PATCH /person/1 HTTP/1.1
@@ -103,7 +110,6 @@ The following request is issued::
 
     {"name": "John", "email": "john@example.org", "age": 29}
 
-
 It can easily be changed to a **form** request using the ``-f``
 (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
 
-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">
         <input type="text" name="name" />
         <input type="file" name="cv" />
     </form>
 
-**Query string parameters** can be added to any request without having to quote
-the ``&`` characters::
+**Query string parameters** can be added to any request without having to
+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``.
-
-A whole request body can be passed in via **``stdin``** instead, in which
+The whole request body can also be passed in **via stdin,** in which
 case it will be used with no further processing::
 
     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
 
 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
-the second one does via ``stdin``::
+they are both default here as the first command has no request data whereas
+the second one has via ``stdin``::
 
     http https://api.github.com/repos/jkbr/httpie | http httpbin.org/post
 
 Note that when the **output is redirected** (like the examples above), HTTPie
-applies a different set of defaults then for console output. Namely colors
-aren't used (can be forced with ``--pretty``) and only the response body
-gets printed (can be overwritten with ``--print``).
+applies a different set of defaults than for a console output. Namely, colors
+aren't used (unless ``--pretty`` is set) and only the response body
+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
 will automatically be set to the appropriate value based on the filename
-extension (using the ``mimetypes`` module). Therefore, the following will
-request will send the verbatim contents of the file with
-``Content-Type: application/xml``::
+extension. Thus, the following will request will send the verbatim contents
+of the file with ``Content-Type: application/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
 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::
 
     #!/bin/bash
@@ -187,12 +192,10 @@ respectively::
 
 
 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]
                 [--pretty | --ugly]
                 [--print OUTPUT_OPTIONS | --verbose | --headers | --body]
@@ -288,58 +291,56 @@ See ``http --help`` for more details::
       --timeout TIMEOUT     Float describes the timeout of the request (Use
                             socket.setdefaulttimeout() as fallback).
 
+
 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
-`issue tracker <https://github.com/jkbr/httpie/issues?state=open>`_ is the
-place to start a discussion about it.
+Before working on a new feature or a bug, please browse the `existing issues`_
+to see whether it has been previously discussed.
 
-To contribute code or documentation, please first browse the existing issues
-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 :)
+Then fork and clone `the repository`_.
 
-To point the ``http`` command to your working copy you can install HTTPie in
-the editable mode::
+To point the ``http`` command to your local branch during development you can
+install HTTPie in an editable mode::
 
     pip install --editable .
 
-It's a good idea to run the existing suite of tests before a pull requests is
-submitted::
+To run the existing suite of tests before a pull request is submitted::
 
     python setup.py test
 
-`Tox <http://tox.testrun.org/>`_ can used to conveniently run tests in all of
-the
-`supported Python environments <https://github.com/jkbr/httpie/blob/master/tox.ini>`_::
+`Tox`_ can also be used to conveniently run tests in all of the
+`supported Python environments`_::
 
     # Install tox
     pip install tox
 
     # Run tests
     tox
 
+
 Changelog
----------
+=========
 
-* `0.2.6dev <https://github.com/jkbr/httpie/compare/0.2.5...master>`_
-    * 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``).
-    * Added ``--check-status`` to exit with an error for HTTP 3xx, 4xx and
-      5xx (3, 4, 5).
+    * Added ``--check-status`` to exit with an error on HTTP 3xx, 4xx and
+      5xx (3, 4, and 5, respectively).
     * 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.)
     * Improved highlighting of HTTP headers.
-    * Added query string parameters (param==value).
+    * Added query string parameters (``param==value``).
     * 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
       improved readability.
     * --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
       ``--verbose``.
     * 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
       ``GET``, or to ``POST`` with data).
     * Fixed --verbose --form.
-    * Added support for `Tox <http://tox.testrun.org/>`_.
-* `0.2.1 <https://github.com/jkbr/httpie/compare/0.2.0...0.2.1>`_ (2012-06-13)
+    * Added support for `Tox`_.
+* `0.2.1`_ (2012-06-13)
     * Added compatibility with ``requests-0.12.1``.
     * Dropped custom JSON and HTTP lexers in favor of the ones newly included
       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 the ability to print the HTTP request as well as the response
       (see ``--print`` and ``--verbose``).
@@ -367,4 +368,34 @@ Changelog
     * Improved syntax highlighting for JSON.
     * Added support for field name escaping.
     * 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
diff --git a/httpie/__init__.py b/httpie/__init__.py
@@ -3,5 +3,5 @@
 
 """
 __author__ = 'Jakub Roztocil'
-__version__ = '0.2.6dev'
+__version__ = '0.2.6'
 __licence__ = 'BSD'