Merge pull request #28 from klehman-rally/vsm-17

Vsm 17

Author: klehman-rally

LICENSE

@@ -1,4 +1,4 @@
-Copyright © Broadcom, Inc. - 2018-2024; CA Technologies - 2015-2018;  Rally Software Development Corp. - 2010-2015
+Copyright © Broadcom, Inc. - 2018-2025; CA Technologies - 2015-2018;  Rally Software Development Corp. - 2010-2015
 All rights reserved.
 
 License for pyral (a Python toolkit for the Rally REST API)
@@ -31,5 +31,4 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.
 
-Rally Software Development® is a registered trademark of Rally Software Development Corp.
 

PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 1.1
 Name: pyral
-Version: 1.6.0
+Version: 1.7.0
 Summary: Python toolkit for Rally REST API
 Home-page: https://github.com/RallyTools/RallyRestToolkitForPython
 Author: Kip Lehman (Broadcom, Agile Operations Division)
 License: BSD
-Download-URL: https://github.com/RallyTools/RallyRestToolkitForPython/raw/master/dists/pyral-1.6.0.zip
+Download-URL: https://github.com/RallyTools/RallyRestToolkitForPython/raw/master/dists/pyral-1.7.0.zip
 Description: This is the README file for pyral, a package implementing a 
         Pythonic interface to the Rally REST API
 
@@ -25,9 +25,9 @@ Description: This is the README file for pyral, a package implementing a
         Requirements
         ------------
 
-        The pyral package requires the use of Kenneth Reitz's requests package using version 2.28.0 or better.
+        The pyral package requires the use of Kenneth Reitz's requests package using version 2.31.x or better.
         The requests package can be found via the Python Package Index site (http://pypi/python.org/index).
-        The most recent release of pyral (1.6.0) has been tested with requests 2.31.0.
+        The most recent release of pyral (1.7.0) has been tested with requests 2.32.5.
 
 
         Installation
@@ -39,6 +39,8 @@ Description: This is the README file for pyral, a package implementing a
 
             pip install pyral
 
+        This approach can probably also use pipex or poetry (although I have not confirmed that).
+        
         Alternatively if you've got the tar.gz or zip distribution on hand, as long as you've
         satisfied the dependency requirement of the requests packages, you can use the setup mechanism.
         Once the requests package has been installed, run the setup.py program supplied with
@@ -64,22 +66,20 @@ Description: This is the README file for pyral, a package implementing a
         Obtain the zip file containing the HTML and CSS files comprising the document set for pyral.
         Unzip in a suitable location and point your web browser to the doc/build/html/index.html file.
 
-        The rendered documentation is also available at http://pyral.readthedocs.io/en/latest/
-        and http://pythonhosted.org/pyral
+        The rendered documentation is also available at http://pyral.readthedocs.io/en/latest/ .
 
 
 Keywords: rally,api
-Requires: requests>=2.28.1
+Requires: requests>=2.31.2
 Platform: any
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Web Environment
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries

README.rst

@@ -38,9 +38,9 @@ pip, the Python package installation utility.::
 Alternatively, if you've got the tar.gz or zip distribution on hand, as long as you've
 satisfied the dependency requirement on the requests package, you can use the setup mechanism.
 Obtain the requests_ package and install it according to that package's directions.
-Use of requests-2.28.x or better is recommended for use with pyral.
+Use of requests-2.32.x or better is recommended for use with pyral.
 The requests_ package can be found via the Python Package Index site (http://pypi/python.org/index).
-The most recent release of pyral (1.6.0) has been tested using requests 2.31.0.
+The most recent release of pyral (1.7.0) has been tested using requests 2.32.5.
 
 Unpack the ``pyral`` distribution file (zip or tar.gz) and then install the pyral_ package.
 
@@ -61,11 +61,11 @@ relevant packages.
 :: 
 
    $ python
-   Python 3.11.5 [other Python interpreter info elided ...]
+   Python 3.13.7 [other Python interpreter info elided ...]
    >> import requests
    >> import pyral
    >> pyral.__version__
-   (1, 6, 0)
+   (1, 7, 0)
 
 
 30 second highlight
@@ -241,13 +241,22 @@ The item names in config files **are** case sensitive.
 Prerequisites
 -------------
 
- * Python 3.9, 3,10, 3.11 or 3.12 (this package not tested with earlier versions of Python 3.x)
- * The requests_ package, 2.28.1 or better, requests 2.31.0 or beyond is recommended.
+ * Python any of (3.12, 3.13 and 3.14) (this package not tested with earlier versions of Python 3.x)
+ * The requests_ package, 2.31.x or better, requests 2.32.5 or beyond is recommended.
 
 .. _requests: http://github.com/kennethreitz/requests
 
 Versions
 --------
+   **1.7.0**
+       Explicitly state support for Python 3.12, 3.13 and 3.14
+       Fixed bug with pryal.restapi.Rally.addCollectionItems method, a collection_name must be provided.
+       Added support for VSM* related entities (VSMProduct, VSMComponent, VSMIncident, VSMChange, VSMDeploy,
+          VSMInvestmentCategorytoInvestmentIntentMap, VSMProductAnalyticsMetric, VSMTarget, VSMMeasure).
+       Added support for creating and updating multiple items of the same entity type in one call via
+          the restapi.createMultiple and restapi.updateMultiple methods.
+       Drop any mention of support for versions 3.11 and earlier.
+
    **1.6.0**
        Eliminated use of six package.
        Added support for Risk, Objective, KeyResult and CapacityPlan* entities.
@@ -359,7 +368,7 @@ TODO
 License
 -------
 
-BSD3-style license. Copyright (c) 2018-2024 Broadcom, Inc., 2015-2018 CA Technologies, 2010-2015 Rally Software Development.
+BSD3-style license. Copyright (c) 2018-2025 Broadcom, Inc., 2015-2018 CA Technologies, 2010-2015 Rally Software Development.
 
 See the LICENSE file provided with the source distribution for full details.
 

README.short

@@ -17,9 +17,9 @@ that may be references or collections via the familiar dot '.' notation.
 Requirements
 ------------
 
-The pyral package requires the use of Kenneth Reitz's requests package using version 2.28.0 or better.
+The pyral package requires the use of Kenneth Reitz's requests package using version 2.31.x or better.
 The requests package can be found via the Python Package Index site (http://pypi/python.org/index).
-The most recent release of pyral (1.6.0) has been tested with requests 2.31.0.
+The most recent release of pyral (1.7.0) has been tested with requests 2.32.5.
 
 
 Installation
@@ -31,6 +31,8 @@ pip, the Python package installation utility.::
 
     pip install pyral
 
+This approach can probably also use pipex or poetry (although I have not confirmed that).
+
 Alternatively if you've got the tar.gz or zip distribution on hand, as long as you've
 satisfied the dependency requirement of the requests packages, you can use the setup mechanism.
 Once the requests package has been installed, run the setup.py program supplied with
@@ -56,6 +58,5 @@ Documentation
 Obtain the zip file containing the HTML and CSS files comprising the document set for pyral.
 Unzip in a suitable location and point your web browser to the doc/build/html/index.html file.
 
-The rendered documentation is also available at http://pyral.readthedocs.io/en/latest/
-and http://pythonhosted.org/pyral
+The rendered documentation is also available at http://pyral.readthedocs.io/en/latest/ .
 

VERSIONS

@@ -162,3 +162,8 @@
     Updated supported Python versions to 3.9, 3.10, 3.11 and 3.12. No longer requires six package.
     Fixed defect in the getAllUsers method that prevented Users beyond the first page from being retrieved.
 
+1.7.0 - Nov 2025
+    Updated supported Python versions to 3.12, 3.13 and 3.14.
+    Updated pytest to 8.3.x.
+    Added support for VSM related Rally entities.
+    Added support for creation/update of the multiple items via restapi.createMultiple and restapi.updateMultiple methods.

build_dist.py

@@ -14,9 +14,9 @@
 import re
 
 PACKAGE_NAME = "pyral"
-VERSION      = "1.6.0"
+VERSION      = "1.7.0"
 
-AUX_FILES  = ['MANIFEST.in', 
+AUX_FILES  = ['MANIFEST', 
               'PKG-INFO', 
               'LICENSE', 
               'README.short', 
@@ -27,6 +27,7 @@
              ]
 EXAMPLES   = ['periscope.py', 
               'getitem.py', 
+              'getitemdesc.py',
               'showdefects.py', 
               'crtask.py', 
               'uptask.py',
@@ -58,7 +59,6 @@
               'doc/build/html/index.html',
               'doc/build/html/overview.html',
               'doc/build/html/interface.html',
-              'doc/build/html/search.html',
               'doc/build/html/searchindex.js',
               'doc/build/html/objects.inv',
               'doc/build/html/_sources',
@@ -90,7 +90,6 @@
               'test/test_query.py',
               'test/test_ranking.py'
               'test/test_recyclebin.py'
-              'test/test_search.py',
               'test/test_wksprj_setting.py',
               'test/test_workspaces.py'
              ]
@@ -155,7 +154,7 @@ def package_meta(filename):
         raise Exception('No such file: %s' % filename)
     with open(filename, 'r') as pcf:
         content = pcf.read()
-    chunk, setup = re.split('setup\(', content, maxsplit=1, flags=re.M)
+    chunk, setup = re.split(r'setup\(', content, maxsplit=1, flags=re.M)
     consties = [line for line in chunk.split("\n") 
                       if (len(line) > 0 and line[0] == " ") or re.search(r'^[A-Z]', line)]
     assignments = "\n".join(consties)

doc/build/html/pyral-1.6.0.docs.html.zip

@@ -41,16 +41,16 @@
 
 # General information about the project.
 project = 'pyral'
-copyright = 'Broadcom 2018-2024, CA Technologies 2015-2017, Rally Software Development 2010-2015'
+copyright = 'Broadcom 2018-2025, CA Technologies 2015-2017, Rally Software Development 2010-2015'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.6.0'
+version = '1.7.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.6.0'
+release = '1.7.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/conf.py

@@ -455,21 +455,6 @@ Core REST methods and CRUD aliases
 
         Returns a boolean indication of the disposition of the attempt to delete the item.
 
-.. method:: search(keywords, \*\*kwargs)
-
-     Given a list of keywords or a string with space separated words, issue
-     the relevant Rally WSAPI search request to find artifacts within the search
-     scope that have any of the keywords in any of the artifact's text fields.
-
-     NOTE: The search functionality must be turned on for your subscription to use this method.
-
-     keyword arguments:
-         - projectScopeUp = true/false (defaults to false)
-         - projectScopeDown = true/false (defaults to false)
-         - pagesize = n  (defaults to 500)
-         - start = n  (defaults to 1)
-         - limit = n  (defaults to no limit)
-
 pyral.Rally instance convenience methods
 ----------------------------------------
 
@@ -681,29 +666,57 @@ pyral.Rally instance convenience methods
 pyral.Rally experimental convenience methods
 --------------------------------------------
 
-.. method:: addCollectionItems(target_item, collection_items)
+.. method:: createMultiple(entity_name, items, fields=None, workspace='current', project='current', **kwargs)
+
+    Given an entityName (for a valid Rally entity type) and a sequence of items (described below) and
+    potential a list of Rally entity attribute names, use the Rally WSAPI /batch endpoint
+    to effect the creation of items corresponding to the elements in list.
+    The elements in the list MUST have information about ALL of the required fields of the Rally entity.
+    The elements CAN have information about non-required fields.
+    An item in the list of items CANNOT have any attributes that are of the Rally COLLECTION type.
+
+    items must be all dict instances OR items must be all pyral entity instances (or instances of "data" class).
+
+.. method:: updateMultiple(entityName, items, fields=None, workspace='current', project='current', **kwargs)
+
+    Given an entityName (for a valid Rally entity type) and a sequence of items (described below)
+    and a list of Rally entity attribute names that are to be updated (fields),
+    use the Rally WSAPI /batch endpoint to effect the update of items corresponding
+    to the elements in list of items.
+    Each item MUST contain an identifying attribute name and value (usually ObjectID is used).
+    The other elements in the list CAN only be attributes that are editable AND
+    an item in the list of elements CANNOT have any attributes that are of the Rally COLLECTION type.
+    If the items have attributes present with non-null values and the attribute name is NOT
+    in the fields list, then those attributes will not be updated via this mechanism.
 
-    Given a target_item and a homogenous list of items whose type appears as a One to Many relationship
-    in the target item, add the collection_items to the corresponding attribute in the target_item.
+    items can be all dict instances OR items can be all pyral entity instances (or instances of "data" class).
+
+.. method:: addCollectionItems(target_item, collection_name, collection_items)
+    
+    Given a target_item, the name of the Collections attribute and a homogenous list of items whose type 
+    appears as a One to Many relationship in the target item, add the collection_items to the corresponding 
+    attribute in the target_item.
+
+    Returns the updated target_item.
 
 ::
 
        ...
        milestones = [milestone_1, milestone_2, milestone_3]
        story = rally.get('story', 'US123') 
-       rally.addCollectionItems(story, milestones)
+       rally.addCollectionItems(story, 'Milestones', milestones)
 
 .. warning:: 
 
         This method only works when the collection attribute on the target_item is Modifiable.
         Consult the Rally WSAPI documentation for the target_item attributes to see whether
         the attribute of interest has a notation of 'Collection Modifiable  yes'.  If there is no 
-        'Colletion Modifiable' notation or the value for that is 'no', then use of this method 
+        'Collection Modifiable' notation or the value for that is 'no', then use of this method
         should not be attempted.
         At this time, the Rally WSAPI schema endpoint does not include information about 
         'Collection Modifiable' for any of the attributes, you'll have to consult the documentation.
 
-.. method:: dropCollectionItems(target_item, collection_items)
+.. method:: dropCollectionItems(target_item, collection_name, collection_items)
 
     Given a target_item and a homogenous list of items whose type appears as a One to Many relationship
     in the target item, delete the collection_items to the corresponding attribute in the target_item 

doc/source/interface.rst

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+
+#################################################################################################
+#
+#  cr_milestone.py -- Create a Milestone instance with a Name and TargetDate
+#
+USAGE = """
+Usage: cr_milestone.py  <name> <target_date>
+"""
+#################################################################################################
+
+import sys, os
+from pyral import Rally, rallyWorkset
+
+#################################################################################################
+
+errout = sys.stderr.write
+
+#################################################################################################
+
+def main(args):
+    options = [opt for opt in args if opt.startswith('--')]
+    args    = [arg for arg in args if arg not in options]
+
+    if len(args) != 2:
+        print("No arguments for the Milestone Name or TargetDate were specified")
+        sys.exit(1)
+
+    server, user, password, apikey, workspace, project = rallyWorkset(options)
+    if apikey:
+        rally = Rally(server, apikey=apikey, workspace=workspace, project=project)
+    else:
+        rally = Rally(server, user=user, password=password, workspace=workspace, project=project)
+
+    target_project = rally.getProject()
+    target_entity_name    = 'Milestone'
+    milestone_name, milestone_target_date = args[:2]
+    info = { 'Name'       : milestone_name,
+             'TargetDate' : milestone_target_date
+           }
+
+
+    print(f"Creating {target_entity_name} ...")
+    milestone = rally.put(target_entity_name, info)
+    print(f"Created  Milestone: {milestone.FormattedID}   OID: {milestone.oid}  Name: {milestone.Name}  TargetDate: {milestone.TargetDate}")
+
+#################################################################################################
+#################################################################################################
+
+if __name__ == '__main__':
+    main(sys.argv[1:])