More tweaks to the readme

diff --git a/README b/README
index b5f5f4f..ab92423 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,23 @@
-== About this library ==
+About this library
+==================
+
+Jenkins is the market leading continuous integration system, originally created by Kohsuke Kawaguchi. This API makes Jenkins even easier to use by providing an easy to use conventional python interface.
+
+Jenkins (and It's predecessor Hudson) are useful projects for automating common development tasks (e.g. unit-testing, production batches) - but they are somewhat Java-centric. Thankfully the designers have provided an excellent and complete REST interface. This library wraps up that interface as more conventional python objects in order to make most Jenkins oriented tasks simpler.
+
+This library can help you:
+
+ * Query the test-results of a completed build
+ * Get a objects representing the latest builds of a job
+ * Search for artefacts by simple criteria
+ * Block until jobs are complete
+ * Install artefacts to custom-specified directory structures
+ * username/password auth support for jenkins instances with auth turned on
+ * Ability to search for builds by subversion revision
+ * Ability to add/remove/query jenkins slaves
+
+Important Links
+===============
 
 Project source code: github: https://github.com/salimfadhley/jenkinsapi
 
@@ -6,3 +25,24 @@ Project documentation: http://packages.python.org/jenkinsapi/
 
 Releases: http://pypi.python.org/pypi/jenkinsapi
 
+Installation
+============
+
+Egg-files for this project are hosted on PyPi. Most Python users should be able to use pip or distribute to automatically install this project.
+
+Most users can do the following:
+
+    easy_install jenkinsapi
+
+If you'd like to install in multi-version mode:
+
+    easy_install -m jenkinsapi
+
+Project Authors
+===============
+
+ * Salim Fadhley (sal@stodge.org) 
+ * Ramon van Alteren (ramon@vanalteren.nl) 
+ * Ruslan Lutsenko (ruslan.lutcenko@gmail.com) 
+
+

diff --git a/jenkinsapi/api.py b/jenkinsapi/api.py
index a8a5be8..a906288 100644 (file)
--- a/jenkinsapi/api.py
+++ b/jenkinsapi/api.py
@@ -48,14 +48,14 @@ def get_artifacts( jenkinsurl, jobid=None, build_no=None, proxyhost=None, proxyp
     log.info("Found %i artifacts in '%s'" % ( len(artifacts.keys() ), build_no ))
     return artifacts
 
-def search_artifacts(jenkinsurl, jobid, artifact_ids=None, same_build=True):
+def search_artifacts(jenkinsurl, jobid, artifact_ids=None ):
     """
     Search the entire history of a jenkins job for a list of artifact names. If same_build
     is true then ensure that all artifacts come from the same build of the job
     """
     if len(artifact_ids) == 0 or artifact_ids is None:
         return []
-    assert same_build, "same_build==False not supported yet"
+    
     jenkinsci = Jenkins( jenkinsurl )
     job = jenkinsci[ jobid ]
     build_ids = job.get_build_ids()
@@ -137,3 +137,31 @@ def install_artifacts(artifacts, dirstruct, installdir, basestaticurl):
                 theartifact.save(destpath)
                 installed.append(destpath)
         return installed
+    
+def search_artifact_by_regexp( jenkinsurl, jobid, artifactRegExp ): 
+    '''
+    @param jenkinsurl: The base URL of the jenkins server
+    @param jobid: The name of the job we are to search through
+    @param artifactRegExp: A compiled regular expression object (not a re-string)
+    '''
+    """
+    Search the entire history of a hudson job for a build which has an artifact whose
+    name matches a supplied regular expression. Return only that artifact.
+    """
+    J = Jenkins( jenkinsurl )
+    j = J[ jobid ] 
+    
+    build_ids = j.getBuildIds()
+    
+    for build_id in build_ids:
+        build = j.getBuild( build_id )
+        
+        artifacts = build.getArtifactDict()
+        
+        for name, art in artifacts.iteritems():
+            md_match = artifactRegExp.search( name )
+            
+            if md_match:
+                return art
+        
+    raise ArtifactsMissing( )