azure-storage-common

Microsoft Azure Storage SDK for Python

.. image:: https://travis-ci.org/Azure/azure-storage-python.svg :target: https://travis-ci.org/Azure/azure-storage-python .. image:: https://img.shields.io/codecov/c/github/azure/azure-storage-python.svg :target: https://codecov.io/gh/Azure/azure-storage-python

This project provides a client library in Python that makes it easy to consume Microsoft Azure Storage services. For documentation please see the Microsoft Azure Python Developer Center_ and our API Reference_ (also available on readthedocs_).

If you are looking for the Service Bus or Azure Management
libraries, please visit
https://github.com/Azure/azure-sdk-for-python.

Compatibility

IMPORTANT: If you have an earlier version of the azure package (version < 1.0), you should uninstall it before installing this package.

You can check the version using pip:

.. code:: shell

pip freeze

If you see azure==0.11.0 (or any version below 1.0), uninstall it first then install it again:

.. code:: shell

pip uninstall azure
pip install azure

If you are upgrading from a version older than 0.30.0, see the upgrade doc, the usage samples in the samples directory, and the ChangeLog and BreakingChanges.

If you are encountering problems_ installing azure storage on Azure Web Apps, upgrading pip_ might help.

IMPORTANT: If you have an earlier version of the azure-storage package (version <= 0.36.0), you should uninstall it before installing the new split packages.

You can check the version using pip:

.. code:: shell

pip freeze

If you see azure-storage==0.36.0 (or any version below 0.36.0), uninstall it first:

.. code:: shell

pip uninstall azure-storage

Features

• Blob

  • Create/Read/Update/Delete Containers
  • Create/Read/Update/Delete Blobs
  • Advanced Blob Operations

• Queue

  • Create/Delete Queues
  • Insert/Peek Queue Messages
  • Advanced Queue Operations

• Files

  • Create/Update/Delete Shares
  • Create/Update/Delete Directories
  • Create/Read/Update/Delete Files
  • Advanced File Operations

Getting Started

Download

The Azure Storage SDK for Python is composed of 5 packages:

• azure-storage-blob

  • Contains the blob service APIs.

• azure-storage-file

  • Contains the file service APIs.

• azure-storage-queue

  • Contains the queue service APIs.

• azure-storage-common

  • Contains common code shared by blob, file and queue.

• azure-storage-nspkg

  • Owns the azure.storage namespace, user should not use this directly.

Note: prior to and including version 0.36.0, there used to be a single package (azure-storage) containing all services. It is no longer supported, and users should install the 3 before-mentioned service packages individually, depending on the need. In addition, the table package is no longer releasing under the azure-storage namespace, please refer to cosmosdb_.

Option 1: Via PyPi

To install via the Python Package Index (PyPI), type:
::

    pip install azure-storage-blob
    pip install azure-storage-file
    pip install azure-storage-queue

Option 2: Source Via Git

To get the source code of the SDK via git just type:

::

git clone git://github.com/Azure/azure-storage-python.git

cd ./azure-storage-python/azure-storage-nspkg
python setup.py install

cd ../azure-storage-common
python setup.py install

cd ../azure-storage-blob
python setup.py install

Replace azure-storage-blob with azure-storage-file or azure-storage-queue, to install the other services.

Option 3: Source Zip

Download a zip of the code via GitHub or PyPi. Then follow the same instructions in option 2.

Minimum Requirements
--------------------

-  Python 2.7, 3.3, 3.4, 3.5, or 3.6.
-  See setup.py for dependencies

Usage
-----

To use this SDK to call Microsoft Azure storage services, you need to
first `create an account`_.

Logging
-----------

To make debugging easier, it is recommended to turn on logging for the logger named 'azure.storage'.
Here are two example configurations:

.. code:: python

    # Basic configuration: configure the root logger, including 'azure.storage'
    logging.basicConfig(format='%(asctime)s %(name)-20s %(levelname)-5s %(message)s', level=logging.INFO)

.. code:: python

    # More advanced configuration allowing more control
    logger = logging.getLogger('azure.storage')
    handler = logging.StreamHandler()
    formatter = logging.Formatter('%(asctime)s %(name)-20s %(levelname)-5s %(message)s')
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    logger.setLevel(logging.INFO)

Here is how we use the logging levels, it is recommended to use INFO:

-  DEBUG: log strings to sign
-  INFO: log outgoing requests and responses, as well as retry attempts
-  WARNING: not used
-  ERROR: log calls that still failed after all the retries

Code Sample
-----------

See the samples directory for blob, queue, and file usage samples.

Need Help?
==========

Be sure to check out the Microsoft Azure `Developer Forums on MSDN`_ or
the `Developer Forums on Stack Overflow`_ if you have trouble with the
provided code.

Contribute Code or Provide Feedback
===================================

If you would like to become an active contributor to this project, please
follow the instructions provided in `Azure Projects Contribution
Guidelines`_. You can find more details for contributing in the `CONTRIBUTING.md doc`_.

If you encounter any bugs with the library, please file an issue in the
`Issues`_ section of the project.

Learn More
==========

-  `Python Developer Center`_
-  `Azure Storage Service`_
-  `Azure Storage Team Blog`_
-  `API Reference`_

.. _Python Developer Center: http://azure.microsoft.com/en-us/develop/python/
.. _API Reference: https://docs.microsoft.com/en-us/python/api/overview/azure/storage/client?view=azure-python
.. _readthedocs: https://azure-storage.readthedocs.io/
.. _here: https://github.com/Azure/azure-storage-python/archive/master.zip
.. _create an account: https://account.windowsazure.com/signup
.. _Developer Forums on MSDN: http://social.msdn.microsoft.com/Forums/windowsazure/en-US/home?forum=windowsazuredata
.. _Developer Forums on Stack Overflow: http://stackoverflow.com/questions/tagged/azure+windows-azure-storage
.. _Azure Projects Contribution Guidelines: http://azure.github.io/guidelines.html
.. _Issues: https://github.com/Azure/azure-storage-python/issues
.. _Azure Storage Service: http://azure.microsoft.com/en-us/documentation/services/storage/
.. _Azure Storage Team Blog: http://blogs.msdn.com/b/windowsazurestorage/
.. _CONTRIBUTING.md doc: CONTRIBUTING.md
.. _problems: https://github.com/Azure/azure-storage-python/issues/219
.. _upgrading pip: https://docs.microsoft.com/en-us/visualstudio/python/managing-python-on-azure-app-service
.. _cosmosdb: https://github.com/Azure/azure-cosmosdb-python