docs for 2.0
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/7234a29b Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/7234a29b Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/7234a29b Branch: refs/heads/trunk Commit: 7234a29b05de1bd05cd6f98f6ace07a148b921f8 Parents: 72d456f Author: Anthony Shaw <anthonys...@apache.org> Authored: Fri Jan 13 15:56:25 2017 +1100 Committer: Anthony Shaw <anthonys...@apache.org> Committed: Fri Jan 13 15:56:25 2017 +1100 ---------------------------------------------------------------------- docs/other/changes_in_2_0.rst | 131 +++++++++++++++++++++++++++++++++++ docs/other/using-http-proxy.rst | 4 +- 2 files changed, 133 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/7234a29b/docs/other/changes_in_2_0.rst ---------------------------------------------------------------------- diff --git a/docs/other/changes_in_2_0.rst b/docs/other/changes_in_2_0.rst index e69de29..2eccbe2 100644 --- a/docs/other/changes_in_2_0.rst +++ b/docs/other/changes_in_2_0.rst @@ -0,0 +1,131 @@ +Changes in Apache Libcloud v2.0.0RC1 +==================================== + +Replacement of urllib with `requests` +------------------------------------- + +Apache Libcloud supports Python 2.6, 2.7 - 3.3 and beyond. To achieve this a package was written within the +Libcloud library to create a generic HTTP client for Python 2 and 3. This package has a custom implementation of a certificate store, searching and TLS preference configuration. One of the first errors to greet new users of Libcloud would be "No CA Certificates were found in CA_CERTS_PATH."... + +In 2.0.0RC1 this implementation has been replaced with the `requests` package, and SSL verification should work against any publically signed HTTPS endpoint by default, without having to provide a CA cert store. + +Other changes include: + +* Enabling HTTP redirects +* Allowing both global and driver-specific HTTP proxy configuration +* Consolidation of the LibcloudHTTPSConnection and LibcloudHTTPConnection into a single class, LibcloudConnection +* Support for streaming responses +* Support for mocking HTTP responses without having to mock the Connection class +* 10% typical performance improvement with the use of persistent TCP connections for each driver instance +* Access to the low-level TCP session is no longer available. Access to .read() on a raw connection will bind around `requests` body or iter_content methods. + + +Allow redirects is enabled by default +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +HTTP redirects are allowed by default in 2.0.0RC1. To disable redirects, set this global variable to False. + +.. code-block:: Python + + import libcloud.httplib_ssl + libcloud.httplib_ssl.ALLOW_REDIRECTS = False + +HTTP/HTTPS Proxies +~~~~~~~~~~~~~~~~~~ + +Enabling a HTTP/HTTPS proxy is still supported and accessed via the driver's connection property or via the 'http_proxy' environment variable. Applying it to a driver will set the proxy for that driver only, using the environment +variable will make a global change. + +.. code-block:: Python + + # option 1 + import os + os.environ.get('http_proxy', 'http://localhost:8888/') + + # option 2 + driver.connection.connection.set_http_proxy(proxy_url='http://localhost:8888') + + +Adding support for Python 3.6 and deprecation of Python 3.2 +----------------------------------------------------------- + +In Apache Libcloud 2.0.0RC1, Python 3.6 is `now supported <https://github.com/apache/libcloud/pull/965>`_ as a primary distribution. + +Python 3.2 support has been dropped in this release and users should either upgrade to 3.3 or a newer version of Python. + +SSL CA certificates are now bundled with the package +---------------------------------------------------- + +In Apache Libcloud 2.0.0RC1, the `Mozilla Trusted Root Store <https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt>`_ is bundled with the package, as part of the `requests` package bundle. +This means that users no longer have to set the path to a CA file either via installing the certifi package, downloading a PEM file or providing a directory in an environment variable. +All connections in Libcloud will assume HTTPS by default, now with 2.0.0, if those HTTPS endpoints have a signed certificate with a trusted CA authority, they will work with Libcloud by default. + +Providing a custom client-side certificate, for example for a development server or a HTTPS proxy is still supported given providing a value to `libcloud.security.CA_CERTS_PATH`. + +This code example would set a HTTP/HTTPS proxy and use a client-generated certificate to verify. + +.. code-block:: Python + + import os + os.environ.set('http_proxy', 'http://localhost:8888/') + + import libcloud.security + libcloud.security.VERIFY_SSL_CERT = True + libcloud.security.CA_CERTS_PATH = '/Users/anthonyshaw/charles.pem' + + +Providing a list of CA trusts is no longer supported +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Apache Libcloud 2.0.0 if you provide a list of more than 1 path or certificate file in `libcloud.security.CA_CERTS_PATH` you will receive a warning and only the first path will be used. This path should be to a .cert or .pem file. +The environment variable REQUESTS_CA_BUNDLE can be used to access the requests library's list of trusted CAs. + +Performance improvements and introduction of sessions +----------------------------------------------------- + +Each instance of libcloud.common.base.Connection will have a LibcloudConnection instance under the `connection` property. In 1.5.0<, there would be 2 connection +class instances, LibcloudHttpConnection and LibcloudHttpsConnection, stored as an instance property `conn_classes`. In 2.0.0 this has been replaced with a single type, +:class:`libcloud.common.base.LibcloudHTTPConnection` that handles both HTTP and HTTPS connections. + +.. code-block:: Python + + def test(): + import libcloud + import libcloud.compute.providers + + d = libcloud.get_driver(libcloud.DriverType.COMPUTE, libcloud.DriverType.COMPUTE.DIMENSIONDATA) + instance = d('anthony', 'mypassword!', 'dd-au') + instance.list_nodes() # is paged + instance.list_images() # is paged + + if __name__ == '__main__': + import timeit + print(timeit.timeit("test()", setup="from __main__ import test", number=5)) + + +This simple test shows a 10% performance improvement between Libcloud 1.5.0 and 2.0.0RC1. + +Changes to the storage API +-------------------------- + +Support for Buffered IO Streams +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The methods `upload_object_via_stream` now supports `file` objects, `BytesIO`, `StringIO` and generators as the iterator. + +.. code-block:: Python + + with open('my_file_to_upload', 'rb') as iterator: + obj = driver.upload_object_via_stream(iterator=iterator, + container=containers[0], + object_name='me.jpg', + extra=extra) + +Other minor changes +------------------- + +- :class:`libcloud.common.base.Connection` will now use `urljoin` to combine the `request_path` and `method` URLs. This means that the URL action will always have a leading slash. + +- The underlying connection classes do not assume HTTP if a non-standard port is used. They will use the preference set in the `secure` flag to the initializer of `Connection`. + +- The storage download_object_as_stream method no longer buffers out file streams twice. http://git-wip-us.apache.org/repos/asf/libcloud/blob/7234a29b/docs/other/using-http-proxy.rst ---------------------------------------------------------------------- diff --git a/docs/other/using-http-proxy.rst b/docs/other/using-http-proxy.rst index 7b9d7ce..1a8699a 100644 --- a/docs/other/using-http-proxy.rst +++ b/docs/other/using-http-proxy.rst @@ -22,9 +22,9 @@ below: * By setting ``http_proxy`` environment variable (this setting is system / process wide) * By passing ``http_proxy`` argument to the - :class:`libcloud.common.base.LibcloudHTTPConnection` class constructor (this + :class:`libcloud.common.base.LibcloudConnection` class constructor (this setting is local to the connection instance) -* By calling :meth:`libcloud.common.base.LibcloudHTTPConnection.set_http_proxy` +* By calling :meth:`libcloud.common.base.LibcloudConnection.set_http_proxy` method (this setting is local to the connection instance) Known limitations
