diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 97a92d03..39c7ddf2 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -6,8 +6,9 @@ This document records all notable changes to `HTTPie `_. This project adheres to `Semantic Versioning `_. -`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 `_. .. _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 diff --git a/README.rst b/README.rst index 0f600b08..15eeb1e3 100644 --- a/README.rst +++ b/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 `_, +where you can select your corresponding HTTPie version as well as run examples directly from the +browser using a `termible.io `_ 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 `_. + 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 `_ +`current development version identifier `_ 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 `_. -Here's a few picks: +Here’s a few picks: * `httpie-api-auth `_: ApiAuth * `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`` diff --git a/httpie/__init__.py b/httpie/__init__.py index eee945f8..574bf64e 100644 --- a/httpie/__init__.py +++ b/httpie/__init__.py @@ -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' diff --git a/setup.cfg b/setup.cfg index 3db9ed60..2b203042 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,4 @@ [wheel] -universal = 1 [tool:pytest] diff --git a/setup.py b/setup.py index 2189469b..084ea47c 100644 --- a/setup.py +++ b/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', + }, )