renamed scrapy.utils.ref module to scrapy.utils.trackref, and improved docstring

--HG--
rename : scrapy/utils/ref.py => scrapy/utils/trackref.py

scrapy/http/request/__init__.py

@@ -11,7 +11,7 @@ from twisted.internet import defer
 
 from scrapy.http.headers import Headers
 from scrapy.utils.url import safe_url_string
-from scrapy.utils.ref import object_ref
+from scrapy.utils.trackref import object_ref
 
 class Request(object_ref):
 

scrapy/http/response/__init__.py

@@ -8,7 +8,7 @@ See documentation in docs/ref/request-response.rst
 import copy
 
 from scrapy.http.headers import Headers
-from scrapy.utils.ref import object_ref
+from scrapy.utils.trackref import object_ref
 
 class Response(object_ref):
 

scrapy/item.py

@@ -1,4 +1,4 @@
-from scrapy.utils.ref import object_ref
+from scrapy.utils.trackref import object_ref
 
 class BaseItem(object_ref):
     """Base class for all scraped items."""
@@ -23,6 +23,7 @@ class ScrapedItem(BaseItem):
         Generate the following format so that items can be deserialized
         easily: ClassName({'attrib': value, ...})
         """
-        reprdict = dict(items for items in self.__dict__.iteritems() if not items[0].startswith('_'))
+        reprdict = dict(items for items in self.__dict__.iteritems() \
+            if not items[0].startswith('_'))
         return "%s(%s)" % (self.__class__.__name__, repr(reprdict))
 

scrapy/management/telnet.py

@@ -15,7 +15,7 @@ from scrapy.core.manager import scrapymanager
 from scrapy.core.engine import scrapyengine
 from scrapy.spider import spiders
 from scrapy.stats import stats
-from scrapy.utils.ref import print_live_refs
+from scrapy.utils.trackref import print_live_refs
 from scrapy.conf import settings
 
 try:

scrapy/utils/trackref.py

@@ -1,5 +1,14 @@
-"""This module provides some functions and classes to record and report live
-references to object instances, for certain classes"""
+"""This module provides some functions and classes to record and report
+references to live object instances.
+
+If you want live objects for a particular class to be tracked, you only have to
+subclass form object_ref (instead of object). Also, remember to turn on
+tracking by enabling the TRACK_REFS setting.
+
+About performance: This library has a minimal performance impact when enabled,
+and no performance penalty at all when disabled (as object_ref becomes just an
+alias to object in that case).
+"""
 
 import weakref
 from collections import defaultdict

scrapy/xpath/selector.py

@@ -11,7 +11,7 @@ from scrapy.xpath.factories import xmlDoc_from_html, xmlDoc_from_xml
 from scrapy.xpath.document import Libxml2Document
 from scrapy.utils.python import flatten, unicode_to_str
 from scrapy.utils.misc import extract_regex
-from scrapy.utils.ref import object_ref
+from scrapy.utils.trackref import object_ref
 from scrapy.utils.decorator import deprecated
 
 class XPathSelector(object_ref):