Documentation updates

cloudbridge/cloud/base/resources.py

@@ -61,12 +61,7 @@ class BaseCloudResource(CloudResource):
     Base implementation of a CloudBridge Resource.
     """
 
-    # Regular expression for valid cloudbridge resource labels.
-    # They, must match the same criteria as GCE labels.
-    # as discussed here: https://github.com/CloudVE/cloudbridge/issues/55
-    #
-    # NOTE: The following regex is based on GCEs internal validation logic,
-    # and is significantly complex to allow for international characters.
+    # Regular expression for valid cloudbridge resource labels and names.
     CB_LABEL_PATTERN = re.compile(r"^[a-z][-a-z0-9]{1,61}[a-z0-9]$")
 
     def __init__(self, provider):

cloudbridge/cloud/interfaces/resources.py

@@ -93,6 +93,9 @@ class CloudResource(object):
         is set at creation time. It is not necessarily unique.
         In Azure, the machine image's name corresponds to cloudbridge's name
         property. In Azure, it also happens to be the same as the id property.
+
+        The name property and the label property share the same character
+        restrictions. see :py:attr:`~LabeledCloudResource.label`
         """
         pass
 
@@ -116,9 +119,11 @@ class LabeledCloudResource(CloudResource):
         in the underlying cloud provider, or be simulated through tags/labels.
 
         The label property adheres to the following restrictions:
-        * Labels cannot be longer than 63 characters
-        * May only contain lowercase letters, numeric characters, underscores,
-          and dashes. International characters are allowed.
+        * Labels cannot be longer than 63 characters.
+        * May only contain ascii characters comprising of lowercase letters,
+          numeric characters, and dashes.
+        * Must begin with an alphanumeric character and end with one
+          (i.e. cannot begin or end with a dash)
 
         Some resources may not support labels, in which case, a
         NotImplementedError will be thrown.

docs/concepts.rst

@@ -1,6 +1,9 @@
 Concepts and Organisation
 =========================
 
+Object types
+------------
+
 Conceptually, CloudBridge consists of the following types of objects.
 
 1. Providers - Represents a connection to a cloud provider, and is
@@ -25,6 +28,37 @@ an instance. Similarly, VolumeService.create() will return a Volume object.
 
 The actual source code structure of CloudBridge also mirrors this organisation.
 
+Object identification and naming
+---------------------------------
+
+In order to function uniformly across across cloud providers, object identity
+and naming must be conceptually consistent. In CloudBridge, there are three
+main properties for identifying and naming an object.
+
+1.Id - The `id` corresponds to a unique identifier that can be reliably used to
+reference a resource. All CloudBridge resources have an id. Most methods in
+CloudBridge services, such as `get`, use the `id` property to identify and
+retrieve objects.
+
+2. Name - The `name` property is a more human-readable identifier for
+a particular resource, and is often useful to display to the end user instead
+of the `id`. While it is often unique, it is not guaranteed to be so, and
+therefore, the `id` property must always be used for uniquely identifying
+objects. All CloudBridge resources have a `name` property. The `name` property
+is often assigned during resource creation, and is often derived from the
+`label` property by appending some unique characters to it. Once assigned
+however, it is unchangeable.
+
+3. Label - Most resources also support a `label` property, which is a user
+changeable value that can be used to describe an object. When creating
+resources, cloudbridge often accepts a `label` property as a parameter.
+The `name` property is derived from the `label`, by appending some unique
+characters to it. However, there are some resources which do not support a
+`label` property, such as key pairs and buckets. In the latter case, the
+`name` can be specified during resource creation, but cannot be changed
+thereafter.
+
+
 Detailed class relationships
 ----------------------------