Using OpenStack Image

Before working with the Image service, you'll need to create a connection
to your OpenStack cloud by following the :doc:connect user guide. This will
provide you with the conn variable used in the examples below.

The primary resource of the Image service is the image.

List Images

An image is a collection of files for a specific operating system
that you use to create or rebuild a server. OpenStack provides
pre-built images <http://docs.openstack.org/image-guide/obtain-images.html>_.
You can also create custom images, or snapshots, from servers that you have
launched. Images come in different formats and are sometimes called virtual
machine images.
（镜像image是根据操作系统不同的一系列的文件集合，你可以使用它去创建和重建一个server。
openstack提供了预建的images，你也可以创建自定义的images，或者从运行的server创建快照。
images有不同的格式，有时候也叫虚拟机镜像。）
.. literalinclude:: ../examples/image/list.py
:pyobject: list_images

Full example: image resource list_

Create Image

Create an image by uploading its data and setting its attributes.
（上传数据和设置属性可以创建一个镜像）
.. literalinclude:: ../examples/image/create.py
:pyobject: upload_image

Full example: image resource create_

.. _download_image-stream-true:

Downloading an Image with stream=True （下载镜像）

As images are often very large pieces of data, storing their entire contents
in the memory of your application can be less than desirable. A more
efficient method may be to iterate over a stream of the response data.
（由于image是拥有很大的数据，存储它到你应用的内存是不可能的。一个更加有效率的的方式是循环迭代一个数据流）
By choosing to stream the response content, you determine the chunk_size
that is appropriate for your needs, meaning only that many bytes of data are
read for each iteration of the loop until all data has been consumed.
See :meth:requests.Response.iter_content for more information, as well
as Requests' :ref:body-content-workflow.
（在选择去下载镜像内容的时候，你决定chunk_size，由你的需求决定。xxx）

When you choose to stream an image download, openstacksdk is no longer
able to compute the checksum of the response data for you. This example
shows how you might do that yourself, in a very similar manner to how
the library calculates checksums for non-streamed responses.
（当你选择去下载一个镜像的数据流，openstacksdk不再有能力去计算下载的数据比例。下面的例子显示如果你你想，你应该怎么做，
使用一个很类似的方式库怎么计算没有下载的数据的校验和）
.. literalinclude:: ../examples/image/download.py
:pyobject: download_image_stream

Downloading an Image with stream=False

If you wish to download an image's contents all at once and to memory,
simply set stream=False, which is the default.
（如果你想去一次性下载一个镜像的内容，保存到内存，那么你设置stream=False）
.. literalinclude:: ../examples/image/download.py
:pyobject: download_image

Full example: image resource download_

Delete Image

Delete an image.
（删除一个镜像）
.. literalinclude:: ../examples/image/delete.py
:pyobject: delete_image

Full example: image resource delete_
（一套例子）
.. _image resource create: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/image/create.py
.. _image resource delete: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/image/delete.py
.. _image resource list: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/image/list.py
.. _image resource download: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/image/download.py