Merge lp:~mbp/testresources/doc into lp:~testresources-developers/testresources/trunk

[Martin Pool]

Hi,

I was using testresources and noticed a few unclear things in the readme - this fixes them.

Also, I was wondering how you would feel about a separate patch to add some specific managers, starting with the tempdir one.

thanks,
-m

[Robert Collins (lifeless)]

Thanks for this, I shall look at it locally to see what the whitespace changes are and merge it.

I'd be happy to have specific managers that depend only on the standard library in testresources. For tempdir though, FixtureResource(fixtures.TempDir) should be all you need. Many things are probably best expressed as fixtures, not as resources + resource managers, and used via FixtureResource.

review: Approve

[Martin Pool (mbp)]

Maybe the testresources readme should mention fixtures too?

[Martin Pool (mbp)]

On 23 October 2012 07:44, Robert Collins <email address hidden> wrote:

> Review: Approve
>
> Thanks for this, I shall look at it locally to see what the whitespace
> changes are and merge it.
>
> I'd be happy to have specific managers that depend only on the standard
> library in testresources. For tempdir though,
> FixtureResource(fixtures.TempDir) should be all you need. Many things are
> probably best expressed as fixtures, not as resources + resource managers,
> and used via FixtureResource.
>
>
Could I persuade you to make a release with FixtureResource some time?

--
Martin

[Robert Collins (lifeless)]

On Thu, Oct 25, 2012 at 10:28 AM, Martin Pool <email address hidden> wrote:
> Maybe the testresources readme should mention fixtures too?

It should :)

[Robert Collins (lifeless)]

On Thu, Oct 25, 2012 at 10:43 AM, Martin Pool <email address hidden> wrote:

> Could I persuade you to make a release with FixtureResource some time?

Here's one I prepared earlier http://pypi.python.org/pypi/testresources :)

-Rob

=== modified file 'README'
--- README	2012-01-25 23:40:13 +0000
+++ README	2012-10-22 20:32:27 +0000
@@ -7,7 +7,7 @@
   license at the users choice. A copy of both licenses are available in the
   project source as Apache-2.0 and BSD. You may not use this file except in
   compliance with one of these two licences.
-  
+
   Unless required by applicable law or agreed to in writing, software
   distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
@@ -44,10 +44,10 @@
 The basic idea of testresources is:
 
 * Tests declare the resources they need in a ``resources`` attribute.
-* When the test is run, the required resource objects are allocated (either 
+* When the test is run, the required resource objects are allocated (either
   newly constructed, or reused), and assigned to attributes of the TestCase.
 
-testresources distinguishes a 'resource manager' (a subclass of 
+testresources distinguishes a 'resource manager' (a subclass of
 ``TestResourceManager``) which acts as a kind of factory, and a 'resource'
 which can be any kind of object returned from the manager class's
 ``getResource`` method.
@@ -75,11 +75,11 @@
 activated.
 
 To declare the use of a resource, set the ``resources`` attribute to a list of
-tuples of ``(attribute_name, resource_factory)``.
+tuples of ``(attribute_name, resource_manager)``.
 
 During setUp, for each declared requirement, the test gains an attribute
 pointing to an allocated resource, which is the result of calling
-``resource_factory.getResource()``.  ``finishedWith`` will be called on each
+``resource_manager.getResource()``.  ``finishedWith`` will be called on each
 resource during tearDown().
 
 For example::
@@ -103,16 +103,19 @@
 overriding these methods:
 
 ``make``
-    Must be overridden in every concrete subclass.  
+    Must be overridden in every concrete subclass.
 
     Returns a new instance of the resource object
-    (the actual resource, not the TestResourceManager).  Doesn't need to worry about 
-    reuse, which is taken care of separately.  This method is only called when a 
-    new resource is definitely needed.  
+    (the actual resource, not the TestResourceManager).  Doesn't need to worry about
+    reuse, which is taken care of separately.  This method is only called when a
+    new resource is definitely needed.
+
+    ``make`` is called by ``getResource``; you should not normally need to override
+    the latter.
 
 ``clean``
-    Cleans up an existing resource instance, eg by deleting a directory or 
-    closing a network connection.  By default this does nothing, which may be 
+    Cleans up an existing resource instance, eg by deleting a directory or
+    closing a network connection.  By default this does nothing, which may be
     appropriate for resources that are automatically garbage collected.
 
 ``reset``
@@ -121,7 +124,7 @@
     faster way to reset them.
 
 ``isDirty``
-    Check whether an existing resource is dirty.  By default this just reports whether 
+    Check whether an existing resource is dirty.  By default this just reports whether
     ``TestResourceManager.dirtied`` has been called.
 
 For instance::
@@ -129,13 +132,13 @@
     class TemporaryDirectoryResource(TestResourceManager):
 
 	def clean(self, resource):
-	    osutils.rmtree(resource) 
+	    shutil.rmtree(resource)
 
         def make(self):
 	    return tempfile.mkdtemp()
 
 	def isDirty(self, resource):
-            # Can't detect when the directory is written to, so assume it 
+            # Can't detect when the directory is written to, so assume it
             # can never be reused.  We could list the directory, but that might
             # not catch it being open as a cwd etc.
 	    return True
@@ -235,6 +238,10 @@
   declared statically, so that testresources can "smooth" resource usage across
   several tests.
 
+  But, you may be able to find some object that is statically declared and reusable
+  to act as the resource, which can then provide methods to generate sub-elements
+  of itself during a test.
+
 * If the resource is held inside the TestResourceManager object, and the
   TestResourceManager is typically constructed inline in the test case
   ``resources`` attribute, how can they be shared across different test