@@ -124,7 +124,7 @@ or you may elect to not specify the '.cfg' suffix.
124124Rally
125125=====
126126
127- The Rally class is the central focus of the **pyral** package. Instantation of this class
127+ The Rally class is the central focus of the **pyral** package. Instantiation of this class
128128 with appropriate and valid target/credential information then provides a means of
129129 interacting with the Rally server.
130130
@@ -144,7 +144,7 @@ Rally
144144 Controls whether a warning is issued if no project is specified
145145 and the default project for the user is not in the workspace specified.
146146 Under those conditions, the project is changed to the first project
147- (alphabetic ordering) in the list of projects for specified workspace.
147+ (alphabetic ordering) in the list of projects for the specified workspace.
148148
149149.. py:class:: Rally (server, user, password, version=1.29, workspace=None, project=None, warn=True)
150150
@@ -189,8 +189,8 @@ Core REST methods and CRUD aliases
189189
190190 keyword arguments:
191191 - fetch = True/False or "List,Of,Attributes,We,Are,Interested,In"
192- - query = 'FieldName = "some value"' or ['fld1 = 10', 'fld2 != "Shamu"', etc.]
193- - instance = True/False (defalts to False)
192+ - query = 'FieldName = "some value"' or ['EstimatedHours = 10', 'MiddleName != "Shamu"', etc.]
193+ - instance = True/False (defaults to False)
194194 - pagesize = n (defaults to 200)
195195 - start = n (defaults to 1)
196196 - limit = n (defaults to no limit)
@@ -202,7 +202,7 @@ Core REST methods and CRUD aliases
202202 Returns a RallyRESTResponse object that has errors and warnings attributes that
203203 should be checked before any further operations on the object are attempted.
204204 The Response object supports the iteration protocol so that the results of the
205- get can be iterated over via either ``for rec in response:`` or ``response.next()``.
205+ `` get`` can be iterated over via either ``for rec in response:`` or ``response.next()``.
206206
207207 If the instance keyword value is True, then an instance of a Rally entity
208208 will be returned instead of a RallyRESTResponse. This can be useful when
@@ -234,13 +234,16 @@ Core REST methods and CRUD aliases
234234.. method:: post (entityName, itemData, workspace=None, project=None)
235235
236236 This method allows for updating a single Rally entity record with the data
237- contained in the itemData dict. The itemData dict may *not* attempt to change
238- the ObjectID value of the entity as the value for the ObjectID is used to identify
237+ contained in the itemData dict. The itemData dict *must* include a
238+ key-value pair for either the ObjectID or when applicable, the FormattedID,
239+ that will uniquely identify the entity to be updated.
240+ The itemData dict may *not* attempt to change the ObjectID value of the
241+ entity as the value for the ObjectID is used to identify
239242 the Rally entity to update. An attempt to update an entity record for
240- which the operational credentials do not include the privileges to update will
241- result in a RallyRESTException being generated.
243+ which the operational credentials do not include the privileges to update
244+ will result in a RallyRESTException being generated.
242245
243- Returns a representation of the item as an instance of a class named for the entity.
246+ Returns a representation of the updated item as an instance of a class named for the entity.
244247
245248.. method:: update
246249
@@ -308,15 +311,17 @@ pyral.Rally instance convenience methods
308311 in the currently active context.
309312
310313
311- .. method:: getProjects(workspace='default' )
314+ .. method:: getProjects(workspace=None )
312315
313316 Return a list of Project instances that are available for the workspace context
314- identified by the workspace keyword argument.
317+ identified by the workspace keyword argument. If no workspace keyword argument
318+ is supplied (or is supplied as None), then the workspace context is that
319+ of the currently selected workspace.
315320
316321
317322.. method:: getUserInfo(oid=None, username=None, name=None)
318323
319- A convenience method to collect specific user related information .
324+ A convenience method to collect the information associated with a specific user .
320325
321326 Caller must provide at least one keyword arg and non-None / non-empty value
322327 to identify the user target on which to obtain information.
@@ -329,10 +334,11 @@ pyral.Rally instance convenience methods
329334 Returns either a single instance of a User entity when the oid keyword argument
330335 matches a User in the system, or a list of User entity items when the username
331336 or name keywords are given and are matched by at least one User in the system.
332- Returns None if no match for keyword argument is found in the system.
337+ Returns None if there is no match in the Rally subscription/workspace for
338+ the keyword argument used to identify the user target.
333339
334340
335- .. method:: getAllUsers()
341+ .. method:: getAllUsers(workspace=None )
336342
337343 This method offers a convenient one-stop means of obtaining usable information
338344 about all users in the named workspace.
@@ -347,11 +353,45 @@ pyral.Rally instance convenience methods
347353 Given an entityName and and attributeName (assumed to be valid for the entityName)
348354 issue a request to obtain a list of allowed values for the attribute.
349355
356+ .. method:: addAttachment(artifact, filename, mime_type='text/plain')
357+
358+ Given an artifact (actual or FormattedID for an artifact), validate that
359+ it exists and then attempt to add an Attachment with the name and
360+ contents of filename into Rally and associate that Attachment with the
361+ Artifact.
362+
363+ .. method:: addAttachments(artifact, attachments)
364+
365+ Given an artifact (either actual or FormattedID) and a list of dicts with
366+ each dict having keys and values for name (or Name), mime_type (or MimeType) and
367+ content_type (or ContentType), add an Attachment corresponding to each dict in
368+ the attachments list and associate it with the referenced Artifact.
369+
370+ .. method:: getAttachment(artifact, filename)
371+
372+ Given a real artifact instance or the FormattedID of an existing artifact,
373+ obtain the attachment named by filename. If there is such an attachment,
374+ return an Attachment instance with hydration for Name, Size, ContentType, Content,
375+ CreationDate and the User that supplied the attachment.
376+ If no such attachment is present, return None
377+
378+ .. method:: getAttachmentNames(artifact)
379+
380+ Given a real artifact instance that is hydrated for at least the Attachments attribute,
381+ return the names (filenames) of the Attachments associated with the artifact.
382+
383+ .. method:: getAttachments(artifact)
384+
385+ Given a real artifact instance, return a list of Attachment records.
386+ Each Attachment record will look like a Rally WSAPI Attachment with
387+ the additional Content attribute that will contain the decoded AttachmentContent.
388+
389+
350390
351391RallyRESTResponse
352392=================
353393
354- A RallyRESTResponse instance is returned from a call to get (find) and several of the
394+ A RallyRESTResponse instance is returned from a call to `` get`` (find) and several of the
355395convenience methods. A instance has the following useful state attributes:
356396
357397 - resource = partial URL identifying the resource for the HTTP Request
0 commit comments