Internal API and doc improvements

vdirsyncer/storage/base.py

@@ -33,6 +33,8 @@ class Storage(object):
         referring to a collection. Otherwise it will be treated as a basepath
         to many collections (e.g. a vdir) and the given collection name will be
         looked for.
+    :param read_only: Whether the synchronization algorithm should avoid writes
+        to this storage. Some storages accept no value other than ``True``.
     '''
 
     fileext = '.txt'
@@ -47,19 +49,22 @@ class Storage(object):
 
     # A value of True means the storage does not support write-methods such as
     # upload, update and delete.  A value of False means the storage does
-    # support those methods, but it may also be used in read-only mode.
+    # support those methods.
     read_only = False
 
     # The attribute values to show in the representation of the storage.
     _repr_attributes = ()
 
-    def __init__(self, instance_name=None, read_only=None):
+    def __init__(self, instance_name=None, read_only=None, collection=None):
         if read_only is None:
             read_only = self.read_only
         if self.read_only and not read_only:
             raise ValueError('This storage is read-only.')
         self.read_only = bool(read_only)
+        if collection and instance_name:
+            instance_name = '{} from {}'.format(collection, instance_name)
         self.instance_name = instance_name
+        self.collection = collection
 
     @classmethod
     def discover(cls, **kwargs):

vdirsyncer/storage/dav.py

@@ -250,18 +250,18 @@ class DavStorage(Storage):
     _session = None
     _repr_attributes = ('username', 'url')
 
-    def __init__(self, url, username='', password='', collection=None,
-                 verify=True, auth=None, useragent=USERAGENT,
-                 unsafe_href_chars='@', verify_fingerprint=None, **kwargs):
+    def __init__(self, url, username='', password='', verify=True, auth=None,
+                 useragent=USERAGENT, unsafe_href_chars='@',
+                 verify_fingerprint=None, **kwargs):
         super(DavStorage, self).__init__(**kwargs)
 
         url = url.rstrip('/') + '/'
+        collection = kwargs.get('collection')
         if collection is not None:
             url = utils.urlparse.urljoin(url, collection)
         self.session = DavSession(url, username, password, verify, auth,
                                   useragent, verify_fingerprint,
                                   dav_header=self.dav_header)
-        self.collection = collection
         self.unsafe_href_chars = unsafe_href_chars
 
         # defined for _repr_attributes

vdirsyncer/storage/filesystem.py

@@ -37,14 +37,13 @@ class FilesystemStorage(Storage):
     storage_name = 'filesystem'
     _repr_attributes = ('path',)
 
-    def __init__(self, path, fileext, collection=None, encoding='utf-8',
-                 create=True, **kwargs):
+    def __init__(self, path, fileext, encoding='utf-8', create=True, **kwargs):
         super(FilesystemStorage, self).__init__(**kwargs)
         path = expand_path(path)
+        collection = kwargs.get('collection')
         if collection is not None:
             path = os.path.join(path, collection)
         checkdir(path, create=create)
-        self.collection = collection
         self.path = path
         self.encoding = encoding
         self.fileext = fileext

vdirsyncer/storage/http.py

@@ -82,9 +82,8 @@ class HttpStorage(Storage):
     _repr_attributes = ('username', 'url')
     _items = None
 
-    def __init__(self, url, username='', password='', collection=None,
-                 verify=True, auth=None, useragent=USERAGENT,
-                 verify_fingerprint=None, **kwargs):
+    def __init__(self, url, username='', password='', verify=True, auth=None,
+                 useragent=USERAGENT, verify_fingerprint=None, **kwargs):
         super(HttpStorage, self).__init__(**kwargs)
 
         if username and not password:
@@ -99,11 +98,11 @@ class HttpStorage(Storage):
         self.username, self.password = username, password
         self.useragent = useragent
 
+        collection = kwargs.get('collection')
         if collection is not None:
             url = urlparse.urljoin(url, collection)
         self.url = url
         self.parsed_url = urlparse.urlparse(self.url)
-        self.collection = collection
 
     def _default_headers(self):
         return {'User-Agent': self.useragent}

vdirsyncer/storage/memory.py

@@ -23,8 +23,8 @@ class MemoryStorage(Storage):
     Saves data in RAM, only useful for testing.
     '''
 
-    def __init__(self, collection=None, **kwargs):
-        if collection is not None:
+    def __init__(self, **kwargs):
+        if kwargs.get('collection') is not None:
             raise ValueError('MemoryStorage does not support collections.')
         self.items = {}  # href => (etag, item)
         super(MemoryStorage, self).__init__(**kwargs)

vdirsyncer/storage/singlefile.py

@@ -60,11 +60,11 @@ class SingleFileStorage(Storage):
 
     _items = None
 
-    def __init__(self, path, encoding='utf-8', create=True,
-                 collection=None, **kwargs):
+    def __init__(self, path, encoding='utf-8', create=True, **kwargs):
         super(SingleFileStorage, self).__init__(**kwargs)
         path = expand_path(path)
 
+        collection = kwargs.get('collection')
         if collection is not None:
             raise ValueError('collection is not a valid argument for {}'
                              .format(type(self).__name__))