Merge pull request #359 from zezha-msft/wastore-master-10-4-2017

Wastore master to Azure master

Author: zezha-msft

.coveragerc

@@ -0,0 +1,6 @@
+[run]
+branch = True
+include =
+	azure*
+omit =
+    azure-storage-nspkg

.gitignore

@@ -53,3 +53,7 @@ src/build
 
 # Azure deployment credentials
 *.pubxml
+
+# code coverage
+.coverage
+.cache/

.travis.yml

@@ -0,0 +1,60 @@
+dist: trusty
+sudo: required
+cache: pip
+language: python
+matrix:
+  include:
+    - os: linux
+      python: "2.7"
+    - os: linux
+      python: "3.3"
+    - os: linux
+      python: "3.4"
+    - os: linux
+      python: "3.5"
+    - os: linux
+      python: "3.6"
+    - os: linux
+      python: "nightly"
+    - os: linux
+      python: "pypy3.5-5.8.0"
+    - os: osx
+      osx_image: xcode7.3
+      language: generic
+  allow_failures:
+    - os: osx
+    - python: "3.3"
+    - python: "pypy3.5-5.8.0"
+    - python: "nightly"
+  fast_finish: true
+# Perform the manual steps on osx to install python3 and activate venv
+before_install:
+  - if [[ -n "$TRAVIS_TAG" && "$TRAVIS_PYTHON_VERSION" != "3.6" ]]; then travis_terminate 0; fi; # Deploy on 3.6
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew update; fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew install python3; fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then python3 -m venv venv; fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then source venv/bin/activate; fi
+install:
+  - pip install -U pip
+  - pip install codecov
+  - pip install coverage
+  - pip install -r requirements.txt
+  - pip install -e azure-storage-common
+  - pip install -e azure-storage-blob
+  - pip install -e azure-storage-file
+  - pip install -e azure-storage-queue
+  - pip install --force-reinstall azure-nspkg==1.0.0
+script:
+  - coverage run -m unittest discover
+after_success:
+  - coverage report
+  - codecov
+notifications:
+  webhooks:
+    urls:
+      - https://outlook.office.com/webhook/a4aad5a1-3f32-42c8-8a5e-903446565be3@72f988bf-86f1-41af-91ab-2d7cd011db47/TravisCI/a018a63e5e994165a2a56b0dd4c62120/3d491bab-ac74-4d43-aeeb-f4b674cb5466
+    on_success: never # default: always
+    on_failure: always # default: always
+    on_start: never   # default: never
+    on_cancel: always # default: always
+    on_error: always # default: always

BreakingChanges.md

@@ -2,6 +2,25 @@
 
 > See the [Change Log](ChangeLog.md) for a summary of storage library changes.
 
+**Note: This changelog is deprecated starting with version XX.XX.XX, please refer to the ChangeLog.md in each package for future change logs.** 
+
+## Version 0.37.0:
+
+### All:
+- The library has been split into 5 different packages:
+    - azure-storage-common
+    - azure-storage-blob
+    - azure-storage-file
+    - azure-storage-queue
+    - azure-storage-nspkg
+- azure.storage.table is now releasing under a different namespace: azure-cosmosdb-table. Please refer to github.com/Azure/azure-cosmosdb-python for more info.
+- The package `azure-storage` is now deprecated.
+- The classes that were directly under azure.storage, not under azure.storage.*(blob, file, queue), are now under azure.storage.common.
+    - Example: azure.storage.retry becomes azure.storage.common.retry
+- The methods on the class SharedAccessSignature were moved into corresponding new subclasses in each service package.
+    - Example: the methods generate_blob and generate_container were moved to BlobSharedAccessSignature in the blob package. BlobSharedAccessSignature inherits generate_account from SharedAccessSignature in common.
+    - Please refer to the reference documentation for more info.
+    
 ## Version 0.34.0:
 
 ### All:

ChangeLog.md

@@ -2,6 +2,32 @@
 
 > See [BreakingChanges](BreakingChanges.md) for a detailed list of API breaks.
 
+**Note: This changelog is deprecated starting with version 0.37.0, please refer to the ChangeLog.md in each package for future change logs.** 
+
+## Version 0.37.0:
+    
+### All:
+- Added logging to the library, the name of the logger is 'azure.storage'. User must add handlers to the logger to output logs. Please refer to readme for more info.
+- Secondary endpoints may now be specified in connection strings, provided the corresponding primary endpoint is specified. See the connection string documentation for details.
+- Fixed an off-by-1 bug in exponential retry interval calculation.
+- The library has been split into 5 different packages:
+    - azure-storage-common
+    - azure-storage-blob
+    - azure-storage-file
+    - azure-storage-queue
+    - azure-storage-nspkg
+- azure.storage.table is now releasing under a different namespace: azure-cosmosdb-table. Please refer to github.com/Azure/azure-cosmosdb-python for more info.
+- The package `azure-storage` is now deprecated.
+- The classes that were directly under azure.storage, not under azure.storage.*(blob, file, queue), are now under azure.storage.common.
+    - Example: azure.storage.retry becomes azure.storage.common.retry
+- The methods on the class SharedAccessSignature were moved into corresponding new subclasses in each service package.
+    - Example: the methods generate_blob and generate_container were moved to BlobSharedAccessSignature in the blob package. BlobSharedAccessSignature inherits generate_account from SharedAccessSignature in common.
+    - Please refer to the reference documentation for more info.
+    
+### File:
+- Added support for creating and deleting share snapshots. See the new 'snapshot_share' method on FileService.
+- Most read operations (such as getting properties and metadata) now include an additional snapshot parameter.
+
 ## Version 0.36.0:
 
 ### Blob:

README.rst

@@ -1,6 +1,11 @@
 Microsoft Azure Storage SDK for Python
 ======================================
 
+.. image:: https://travis-ci.org/Azure/azure-storage-python.svg?branch=dev
+    :target: https://travis-ci.org/Azure/azure-storage-python
+.. image:: https://img.shields.io/codecov/c/github/azure/azure-storage-python/dev.svg
+    :target: https://codecov.io/gh/Azure/azure-storage-python/branch/dev
+
 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`_ Page.
@@ -32,9 +37,23 @@ If you see azure==0.11.0 (or any version below 1.0), uninstall it first then ins
 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,
+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
 ========
@@ -51,13 +70,6 @@ Features
    -  Insert/Peek Queue Messages
    -  Advanced Queue Operations
 
--  Table
-
-   -  Create/Read/Update/Delete Tables
-   -  Create/Read/Update/Delete Entities
-   -  Batch operations
-   -  Advanced Table Operations
-
 -  Files
 
    -  Create/Update/Delete Shares
@@ -71,13 +83,41 @@ 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
+    pip install azure-storage-blob
+    pip install azure-storage-file
+    pip install azure-storage-queue
 
 Option 2: Source Via Git
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -87,23 +127,28 @@ 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
+
+    cd ./azure-storage-python/azure-storage-nspkg
     python setup.py install
 
-Option 3: Source Zip
-~~~~~~~~~~~~~~~~~~~~
+    cd ../azure-storage-common
+    python setup.py install
 
-Download a zip of the code via GitHub or PyPi. Then, type:
+    cd ../azure-storage-blob
+    python setup.py install
 
-::
 
-    cd ./azure-storage-python
-    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, or 3.5.
+-  Python 2.7, 3.3, 3.4, 3.5, or 3.6.
 -  See setup.py for dependencies
 
 Usage
@@ -112,10 +157,38 @@ 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, table, and file usage samples.
+See the samples directory for blob, queue, and file usage samples.
 
 Need Help?
 ==========
@@ -154,4 +227,5 @@ Learn More
 .. _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
+.. _upgrading pip: https://docs.microsoft.com/en-us/visualstudio/python/managing-python-on-azure-app-service
+.. _cosmosdb: https://github.com/Azure/azure-cosmosdb-python

azure-storage-blob/BreakingChanges.md

@@ -0,0 +1,3 @@
+# Breaking Changes azure-storage-blob
+
+> See the [Change Log](ChangeLog.md) for a summary of storage library changes.

azure-storage-blob/ChangeLog.md

@@ -0,0 +1,3 @@
+# Change Log azure-storage-blob
+
+> See [BreakingChanges](BreakingChanges.md) for a detailed list of API breaks.

MANIFEST.in renamed to azure-storage-blob/MANIFEST.in

@@ -1,3 +1,2 @@
 include *.rst
-exclude azure/__init__.py
 include azure_bdist_wheel.py