better workspace and project scoping behavior, fixed inappropriate message on request timeout

Author: klehman-rally

MANIFEST

@@ -1,7 +1,6 @@
+LICENSE
 README.short
 README.rst
-LICENSE
-MANIFEST
 setup.py
 template.cfg
 rallyfire.py
@@ -15,6 +14,6 @@ pyral/restapi.py
 examples/getitem.py
 examples/periscope.py
 examples/showdefects.py
+examples/statecounts.py
 examples/crtask.py
 examples/uptask.py
-examples/statecounts.py

dists/pyral-0.8.11.tar.gz

@@ -1,5 +1,5 @@
 __version__ = (0, 8, 11)
 from .config    import rallySettings
-from .restapi   import Rally, RallyRESTAPIError
+from .restapi   import Rally, RallyRESTAPIError, RallyUrlBuilder
 from .rallyresp import RallyRESTResponse
 

dists/pyral-0.8.11.zip

@@ -29,6 +29,7 @@
 REQUEST_TIME_LIMIT = 5  # in seconds
 
 IPV4_ADDRESS_PATT = re.compile(r'^\d+\.\d+\.\d+\.\d+$')
+FORMATTED_ID_PATT = re.compile(r'^[A-Z]{1,2}\d+$')
 
 ##################################################################################################
 
@@ -72,7 +73,7 @@ def serviceURL(self):
     def identity(self):
         workspace = self.workspace or 'None'
         project   = self.project   or 'None'
-        return " | ".join([self.server, self.user, self.password, workspace, project])
+        return " | ".join([self.server, self.user, self.password, workspace or "None", project or "None"])
 
     def __repr__(self):
         return self.identity()
@@ -161,7 +162,7 @@ def check(self, server):
             if response.status_code == 404:
                 if elapsed >= float(REQUEST_TIME_LIMIT):
                     problem = "Request timed out on attempt to reach %s" % server
-                if response.errors and 'NoneType' in response.errors[0]:
+                elif response.errors and 'NoneType' in response.errors[0]:
                     problem = "Target Rally host: '%s' non-existent or unreachable" % server
                 else:
                     #sys.stderr.write("404 Response for request\n")
@@ -184,6 +185,7 @@ def check(self, server):
 ##        print " RallyContextHelper.check got the User info ..."
 ##        sys.stdout.flush()
 ##
+        self.user_oid = response.next().oid
         self._loadSubscription()
         self._getDefaults(response)
         self._getWorkspacesAndProjects(workspace=self._defaultWorkspace, project=self._defaultProject)
@@ -259,9 +261,15 @@ def _getDefaults(self, response):
         if not self._projects:
             self._projects      = {self._defaultWorkspace : [self._defaultProject]}
         if not self._workspace_ref:
-            self._workspace_ref = {self._defaultWorkspace : wkspace_ref}
+            if wkspace_ref.endswith('.js'):
+                wkspace_ref = wkspace_ref[:-3]
+            short_ref = "/".join(wkspace_ref.split('/')[-2:])  # we only need the 'workspace/<oid>' part to be a valid ref
+            self._workspace_ref = {self._defaultWorkspace : short_ref}
         if not self._project_ref:
-            self._project_ref   = {self._defaultWorkspace : {self._defaultProject : proj_ref}}
+            if proj_ref.endswith('.js'):
+                proj_ref = proj_ref[:-3]
+            short_ref = "/".join(proj_ref.split('/')[-2:])  # we only need the 'project/<oid>' part to be a valid ref
+            self._project_ref   = {self._defaultWorkspace : {self._defaultProject : short_ref}}
         self.defaultContext = RallyContext(self.server, 
                                            self.user, 
                                            self.password,
@@ -493,7 +501,11 @@ def identifyContext(self, **kwargs):
             self.context.workspace = workspace
 
         project = None        
-        if 'project' in kwargs and kwargs['project']:
+        if 'project' in kwargs:
+            if not kwargs['project']:
+                self.context.project = None
+                return self.context, augments
+
             project = kwargs['project']
             wks = workspace or self._currentWorkspace or self._defaultWorkspace
             if project not in self._projects[wks]:
@@ -555,8 +567,9 @@ def _getWorkspacesAndProjects(self, **kwargs):
             if workspace.Name not in self._workspaces:
                 self._workspaces.append(workspace.Name)
                 #self._workspace_ref[workspace.Name] = workspace._ref
-                # we only need the workspace/123534 section to qualify as a valid ref
-                self._workspace_ref[workspace.Name] = '/'.join(workspace._ref[:-3].split('/')[-2:])
+                # we only need the 'workspace/<oid>' fragment to qualify as a valid ref
+                wksp_ref = workspace._ref[:-3] if workspace._ref.endswith('.js') else workspace._ref
+                self._workspace_ref[workspace.Name] = '/'.join(wksp_ref.split('/')[-2:])
             if workspace.Name not in self._projects:
                 self._projects[   workspace.Name] = []
                 self._project_ref[workspace.Name] = {}

pyral/__init__.py

@@ -4,8 +4,9 @@
 #
 #  pyral.restapi - Python Rally REST API module
 #          round 8 version with GET, PUT, POST and DELETE operations, support multiple instances
-#          dependencies:
+#          notable dependencies:
 #               requests v0.8.2 or better
+#               requests v0.9.3 recommended (0.10.x no longer works for Python 2.5)
 #
 ###################################################################################################
 
@@ -17,7 +18,6 @@
 import time
 import urllib
 import json
-from operator import itemgetter
 
 import requests   
 
@@ -97,19 +97,21 @@ def getResourceByOID(context, entity, oid, **kwargs):
 ##        print ""
 ##        print " apparently no key to match: -->%s<--" % context
 ##        print " context is a %s" % type(context)
+##
     rally = rallyContext.get('rally')
     resp = rally._getResourceByOID(context, entity, oid, **kwargs)
     if 'unwrap' not in kwargs or not kwargs.get('unwrap', False):
         return resp
     response = RallyRESTResponse(rally.session, context, "%s.x" % entity, resp, "full", 1)
     return response
 
+
 #  these imports have to take place after the prior class and function defs 
 from .rallyresp import RallyRESTResponse, ErrorResponse
 from .hydrate   import EntityHydrator
 from .context   import RallyContext, RallyContextHelper
 
-__all__ = ["Rally", "getResourceByOID", "hydrateAnInstance"]
+__all__ = ["Rally", "getResourceByOID", "hydrateAnInstance", "RallyUrlBuilder"]
 
 
 def _createShellInstance(context, entity_name, item_name, item_ref):
@@ -127,7 +129,6 @@ def _createShellInstance(context, entity_name, item_name, item_ref):
     hydrator = EntityHydrator(context, hydration="shell")
     return hydrator.hydrateInstance(item)
 
-
 ##################################################################################################
 
 class Rally(object):
@@ -147,8 +148,6 @@ def __init__(self, server=SERVER, user=USER_NAME, password=PASSWORD,
         self.version   = version
         self._inflated = False
         self.service_url = "%s://%s/%s" % (PROTOCOL, self.server, WEB_SERVICE % self.version)
-        self._use_workspace_default = True
-        self._use_project_default   = True
         self.hydration   = "full"
         self._log        = False
         self._logDest    = None
@@ -188,20 +187,16 @@ def __init__(self, server=SERVER, user=USER_NAME, password=PASSWORD,
            and kwargs['workspace'] != 'default':
             if self.contextHelper.isAccessibleWorkspaceName(kwargs['workspace']):
                 self.contextHelper.setWorkspace(kwargs['workspace'])
-                self._use_workspace_default = False
                 __adjust_cache = True
             else:
                  warning("WARNING: Unable to use your workspace specification, that value is not listed in your subscription\n")
 
         if 'project' in kwargs and kwargs['project'] != self.contextHelper.currentContext().project \
            and kwargs['project'] != 'default':
             accessibleProjects = [name for name, ref in self.contextHelper.getAccessibleProjects(workspace='current')]
-##
-##            print "accessible projects: %s" % ", ".join(accessibleProjects)
-##
+
             if kwargs['project'] in accessibleProjects:
                 self.contextHelper.setProject(kwargs['project'])
-                self._use_project_default = False
                 __adjust_cache = True
             else:
                 issue = ("Unable to use your project specification of '%s', " 
@@ -232,9 +227,7 @@ def __init__(self, server=SERVER, user=USER_NAME, password=PASSWORD,
 
         if __adjust_cache:
             _rallyCache[self.contextHelper.currentContext()] = {'rally' : self}
-##
-##        print "successfully intitialized a new Rally ifc ..."
-##
+
 
     def _wpCacheStatus(self):
         """
@@ -368,7 +361,6 @@ def getProject(self):
         proj_name, proj_ref = self.contextHelper.getProject()
         return _createShellInstance(context, 'Project', proj_name, proj_ref)
 
-
     def getProjects(self, workspace=None):
         """
             Return a list of minimally hydrated Project instances
@@ -503,16 +495,13 @@ def _getResourceByOID(self, context, entity, oid, **kwargs):
 ##            print "_getResourceByOID, current contextDict: %s" % repr(contextDict)
 ##            sys.stdout.flush()
 ##
-            
             context, augments = self.contextHelper.identifyContext(**contextDict)
             if augments:
                 resource += ("?" + "&".join(augments))
 ##
 ##            print "_getResourceByOID, modified contextDict: %s" % repr(context.asDict())
 ##            sys.stdout.flush()
 ##
-
-
         full_resource_url = "%s/%s" % (self.service_url, resource)
         if self._logAttrGet:
             self._logDest.write('%s GET %s\n' % (timestamp(), resource))
@@ -631,11 +620,17 @@ def get(self, entity, fetch=False, query=None, order=None, **kwargs):
             context, augments = self.contextHelper.identifyContext(**kwargs)
             workspace_ref = self.contextHelper.currentWorkspaceRef()
             project_ref   = self.contextHelper.currentProjectRef()
-            if workspace_ref:
-                resource.augmentWorkspace(augments, workspace_ref, self._use_workspace_default)
-                if project_ref:
-                    resource.augmentProject(augments, project_ref, self._use_project_default)
-                    resource.augmentScoping(augments)
+##
+##            print "   workspace_ref: %s"   % workspace_ref
+##            print "     project_ref:   %s" %   project_ref
+##
+            if workspace_ref:   # TODO: would we ever _not_ have a workspace_ref?
+                if 'workspace' not in kwargs or ('workspace' in kwargs and kwargs['workspace'] is not None):
+                    resource.augmentWorkspace(augments, workspace_ref)
+                    if project_ref:
+                        if 'project' not in kwargs or ('project' in kwargs and kwargs['project'] is not None):
+                            resource.augmentProject(augments, project_ref)
+                            resource.augmentScoping(augments)
         resource = resource.build()  # can also use resource = resource.build(pretty=True)
         full_resource_url = "%s/%s" % (self.service_url, resource)
 
@@ -699,15 +694,23 @@ def get(self, entity, fetch=False, query=None, order=None, **kwargs):
     find = get # offer interface approximately matching Ruby Rally REST API, App SDK Javascript RallyDataSource
 
 
-    def put(self, entityName, itemData, workspace=None, project=None, **kwargs):
+    def put(self, entityName, itemData, workspace='current', project='current', **kwargs):
         """
-            Return the newly created target entity item
+            Given a Rally entityName, a dict with data that the newly created entity should contain,
+            issue the REST call and return the newly created target entity item.
         """
+        # see if we need to transform workspace / project values of 'current' to actual
+        if workspace == 'current':
+            workspace = self.getWorkspace().Name  # just need the Name here
+        if project == 'current':
+            project = self.getProject().Name  # just need the Name here
+
         entityName = self._officialRallyEntityName(entityName)
+
         resource = "%s/create.js" % entityName.lower()
         context, augments = self.contextHelper.identifyContext(workspace=workspace, project=project)
         if augments:
-            resource += ("&" + "&".join(augments))
+            resource += ("?" + "&".join(augments))
         full_resource_url = "%s/%s" % (self.service_url, resource)
         item = {entityName: itemData}
         payload = json.dumps(item)
@@ -740,7 +743,17 @@ def put(self, entityName, itemData, workspace=None, project=None, **kwargs):
     create = put  # a more intuitive alias for the operation
 
 
-    def post(self, entityName, itemData, workspace=None, project=None, **kwargs):
+    def post(self, entityName, itemData, workspace='current', project='current', **kwargs):
+        """
+            Given a Rally entityName, a dict with data that the entity should be updated with,
+            issue the REST call and return a representation of updated target entity item.
+        """
+        # see if we need to transform workspace / project values of 'current' to actual
+        if workspace == 'current':
+            workspace = self.getWorkspace().Name  # just need the Name here
+        if project == 'current':
+            project = self.getProject().Name  # just need the Name here
+
         entityName = self._officialRallyEntityName(entityName)
 
         oid = itemData.get('ObjectID', None)
@@ -751,7 +764,7 @@ def post(self, entityName, itemData, workspace=None, project=None, **kwargs):
             fmtIdQuery = 'FormattedID = "%s"' % formattedID
             response = self.get(entityName, fetch="ObjectID", query=fmtIdQuery, 
                                 workspace=workspace, project=project)
-            if response.status_code != 200:
+            if response.status_code != 200 or response.resultCount == 0:
                 raise RallyRESTAPIError('Target %s %s could not be located' % (entityName, formattedID))
 
             target = response.next()
@@ -764,7 +777,7 @@ def post(self, entityName, itemData, workspace=None, project=None, **kwargs):
         resource = '%s/%s.js' % (entityName.lower(), oid) 
         context, augments = self.contextHelper.identifyContext(workspace=workspace, project=project)
         if augments:
-            resource += ("&" + "&".join(augments))
+            resource += ("?" + "&".join(augments))
         full_resource_url = "%s/%s" % (self.service_url, resource)
 ##
 ##        print "resource: %s" % resource
@@ -787,8 +800,20 @@ def post(self, entityName, itemData, workspace=None, project=None, **kwargs):
     update = post  # a more intuitive alias for the operation
 
 
-    def delete(self, entityName, itemIdent, workspace=None, project=None, **kwargs):
+    def delete(self, entityName, itemIdent, workspace='current', project='current', **kwargs):
+        """
+            Given a Rally entityName, an identification of a specific Rally instnace of that 
+            entity (in either OID or FormattedID format), issue the REST DELETE call and 
+            return an indication of whether the delete operation was successful.
+        """
+        # see if we need to transform workspace / project values of 'current' to actual
+        if workspace == 'current':
+            workspace = self.getWorkspace().Name  # just need the Name here
+        if project == 'current':
+            project = self.getProject()[0].Name  # just need the Name here
+
         entityName = self._officialRallyEntityName(entityName)
+
         # guess at whether itemIdent is an ObjectID or FormattedID via 
         # regex matching (all digits or 1-2 upcase chars + digits)
         objectID = itemIdent  # at first assume itemIdent is the ObjectID
@@ -820,7 +845,7 @@ def delete(self, entityName, itemIdent, workspace=None, project=None, **kwargs):
                 self._logDest.flush()
 ##
 ##            if kwargs.get('debug', False):
-##                print response
+##                print response.status_code, response.headers, response.content
 ##
             errorResponse = ErrorResponse(response.status_code, response.content)
             response = RallyRESTResponse(self.session, context, resource, errorResponse, self.hydration, 0)
@@ -847,7 +872,7 @@ def delete(self, entityName, itemIdent, workspace=None, project=None, **kwargs):
 
     def allowedValueAlias(self, entity, refUrl):
         """
-            use the _allowedValueAlias as a cache. A cache hit results from 
+            Use the _allowedValueAlias as a cache. A cache hit results from 
             having an entity key in _allowedValueAlias AND and entry for the OID 
             contained in the refUrl, the return is the OID and the alias value.
             If there is no cache hit for the entity, issue a GET against
@@ -987,7 +1012,6 @@ def build(self, pretty=None):
         if self.pretty:
             qualifiers.append('pretty=true')
 
-        #resource += ("&" + "&".join(qualifiers))
         resource += "&".join(qualifiers)
         return resource
 
@@ -1029,20 +1053,15 @@ def _encode(condition):
 
         return None
 
-
-    def augmentWorkspace(self, augments, workspace_ref, use_default):
+    def augmentWorkspace(self, augments, workspace_ref):
         wksp_augment = [aug for aug in augments if aug.startswith('workspace=')]
-        if use_default:
-            self.workspace = "workspace=%s" % workspace_ref
+        self.workspace = "workspace=%s" % workspace_ref
         if wksp_augment:
             self.workspace = wksp_augment[0]
 
-
-    def augmentProject(self, augments, project_ref,  use_default):
+    def augmentProject(self, augments, project_ref):
         proj_augment = [aug for aug in augments if aug.startswith('project=')]
         self.project = "project=%s" % project_ref
-        if use_default:
-            self.project = "project=%s" % project_ref
         if proj_augment:
             self.project = proj_augment[0]