README.rst
1Microsoft Azure Storage SDK for Python
2======================================
3
4.. image:: https://travis-ci.org/Azure/azure-storage-python.svg
5 :target: https://travis-ci.org/Azure/azure-storage-python
6.. image:: https://img.shields.io/codecov/c/github/azure/azure-storage-python.svg
7 :target: https://codecov.io/gh/Azure/azure-storage-python
8
9This project provides a client library in Python that makes it easy to
10consume Microsoft Azure Storage services. For documentation please see
11the Microsoft Azure `Python Developer Center`_ and our `API Reference`_ (also available on `readthedocs`_).
12
13 If you are looking for the Service Bus or Azure Management
14 libraries, please visit
15 https://github.com/Azure/azure-sdk-for-python.
16
17
18Compatibility
19=============
20
21**IMPORTANT**: If you have an earlier version of the azure package
22(version < 1.0), you should uninstall it before installing this package.
23
24You can check the version using pip:
25
26.. code:: shell
27
28 pip freeze
29
30If you see azure==0.11.0 (or any version below 1.0), uninstall it first then install it again:
31
32.. code:: shell
33
34 pip uninstall azure
35 pip install azure
36
37If you are upgrading from a version older than 0.30.0, see the upgrade doc, the
38usage samples in the samples directory, and the ChangeLog and BreakingChanges.
39
40If you are encountering `problems`_ installing azure storage on Azure Web Apps,
41`upgrading pip`_ might help.
42
43**IMPORTANT**: If you have an earlier version of the azure-storage package
44(version <= 0.36.0), you should uninstall it before installing the new split packages.
45
46You can check the version using pip:
47
48.. code:: shell
49
50 pip freeze
51
52If you see azure-storage==0.36.0 (or any version below 0.36.0), uninstall it first:
53
54.. code:: shell
55
56 pip uninstall azure-storage
57
58Features
59========
60
61- Blob
62
63 - Create/Read/Update/Delete Containers
64 - Create/Read/Update/Delete Blobs
65 - Advanced Blob Operations
66
67- Queue
68
69 - Create/Delete Queues
70 - Insert/Peek Queue Messages
71 - Advanced Queue Operations
72
73- Files
74
75 - Create/Update/Delete Shares
76 - Create/Update/Delete Directories
77 - Create/Read/Update/Delete Files
78 - Advanced File Operations
79
80Getting Started
81===============
82
83Download
84--------
85
86The Azure Storage SDK for Python is composed of 5 packages:
87
88- azure-storage-blob
89
90 - Contains the blob service APIs.
91
92- azure-storage-file
93
94 - Contains the file service APIs.
95
96- azure-storage-queue
97
98 - Contains the queue service APIs.
99
100- azure-storage-common
101
102 - Contains common code shared by blob, file and queue.
103
104- azure-storage-nspkg
105
106 - Owns the azure.storage namespace, user should not use this directly.
107
108**Note**: prior to and including version 0.36.0, there used to be a single package (azure-storage) containing all services.
109It is no longer supported, and users should install the 3 before-mentioned service packages individually, depending on the need.
110In addition, the **table** package is no longer releasing under the azure-storage namespace, please refer to `cosmosdb`_.
111
112Option 1: Via PyPi
113~~~~~~~~~~~~~~~~~~
114
115To install via the Python Package Index (PyPI), type:
116::
117
118 pip install azure-storage-blob
119 pip install azure-storage-file
120 pip install azure-storage-queue
121
122Option 2: Source Via Git
123~~~~~~~~~~~~~~~~~~~~~~~~
124
125To get the source code of the SDK via git just type:
126
127::
128
129 git clone git://github.com/Azure/azure-storage-python.git
130
131 cd ./azure-storage-python/azure-storage-nspkg
132 python setup.py install
133
134 cd ../azure-storage-common
135 python setup.py install
136
137 cd ../azure-storage-blob
138 python setup.py install
139
140
141Replace azure-storage-blob with azure-storage-file or azure-storage-queue, to install the other services.
142
143Option 3: Source Zip
144~~~~~~~~~~~~~~~~~~~~
145
146Download a zip of the code via GitHub or PyPi. Then follow the same instructions in option 2.
147
148Minimum Requirements
149--------------------
150
151- Python 2.7, 3.3, 3.4, 3.5, or 3.6.
152- See setup.py for dependencies
153
154Usage
155-----
156
157To use this SDK to call Microsoft Azure storage services, you need to
158first `create an account`_.
159
160Logging
161-----------
162
163To make debugging easier, it is recommended to turn on logging for the logger named 'azure.storage'.
164Here are two example configurations:
165
166.. code:: python
167
168 # Basic configuration: configure the root logger, including 'azure.storage'
169 logging.basicConfig(format='%(asctime)s %(name)-20s %(levelname)-5s %(message)s', level=logging.INFO)
170
171.. code:: python
172
173 # More advanced configuration allowing more control
174 logger = logging.getLogger('azure.storage')
175 handler = logging.StreamHandler()
176 formatter = logging.Formatter('%(asctime)s %(name)-20s %(levelname)-5s %(message)s')
177 handler.setFormatter(formatter)
178 logger.addHandler(handler)
179 logger.setLevel(logging.INFO)
180
181Here is how we use the logging levels, it is recommended to use INFO:
182
183- DEBUG: log strings to sign
184- INFO: log outgoing requests and responses, as well as retry attempts
185- WARNING: not used
186- ERROR: log calls that still failed after all the retries
187
188Code Sample
189-----------
190
191See the samples directory for blob, queue, and file usage samples.
192
193Need Help?
194==========
195
196Be sure to check out the Microsoft Azure `Developer Forums on MSDN`_ or
197the `Developer Forums on Stack Overflow`_ if you have trouble with the
198provided code.
199
200Contribute Code or Provide Feedback
201===================================
202
203If you would like to become an active contributor to this project, please
204follow the instructions provided in `Azure Projects Contribution
205Guidelines`_. You can find more details for contributing in the `CONTRIBUTING.md doc`_.
206
207If you encounter any bugs with the library, please file an issue in the
208`Issues`_ section of the project.
209
210Learn More
211==========
212
213- `Python Developer Center`_
214- `Azure Storage Service`_
215- `Azure Storage Team Blog`_
216- `API Reference`_
217
218.. _Python Developer Center: http://azure.microsoft.com/en-us/develop/python/
219.. _API Reference: https://docs.microsoft.com/en-us/python/api/overview/azure/storage/client?view=azure-python
220.. _readthedocs: https://azure-storage.readthedocs.io/
221.. _here: https://github.com/Azure/azure-storage-python/archive/master.zip
222.. _create an account: https://account.windowsazure.com/signup
223.. _Developer Forums on MSDN: http://social.msdn.microsoft.com/Forums/windowsazure/en-US/home?forum=windowsazuredata
224.. _Developer Forums on Stack Overflow: http://stackoverflow.com/questions/tagged/azure+windows-azure-storage
225.. _Azure Projects Contribution Guidelines: http://azure.github.io/guidelines.html
226.. _Issues: https://github.com/Azure/azure-storage-python/issues
227.. _Azure Storage Service: http://azure.microsoft.com/en-us/documentation/services/storage/
228.. _Azure Storage Team Blog: http://blogs.msdn.com/b/windowsazurestorage/
229.. _CONTRIBUTING.md doc: CONTRIBUTING.md
230.. _problems: https://github.com/Azure/azure-storage-python/issues/219
231.. _upgrading pip: https://docs.microsoft.com/en-us/visualstudio/python/managing-python-on-azure-app-service
232.. _cosmosdb: https://github.com/Azure/azure-cosmosdb-python
233
