2.1.0

#488 #840 #895

CHANGELOG.rst

@@ -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

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``

httpie/__init__.py

@@ -3,6 +3,6 @@
 
 """
 
-__version__ = '2.1.0-dev'
+__version__ = '2.1.0'
 __author__ = 'Jakub Roztocil'
 __licence__ = 'BSD'

setup.cfg

@@ -1,5 +1,4 @@
 [wheel]
-universal = 1
 
 
 [tool:pytest]