- Deprecation warnings related to import of the following API functions were

  added: ``pyramid.traversal.find_model``, ``pyramid.traversal.model_path``,
  ``pyramid.traversal.model_path_tuple``, ``pyramid.url.model_url``.  The
  instructions emitted by the deprecation warnings instruct the developer to
  change these method spellings to their ``resource`` equivalents.  This is a
  consequence of the mass concept rename of "model" to "resource" performed
  in 1.0a7.

4 files changed, 56 insertions, 17 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index b17dfe88b..73f0b3d4b 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -31,6 +31,17 @@ Documentation
 - Document the ``request.override_renderer`` attribute within the narrative
   "Renderers" chapter in a section named "Overriding A Renderer at Runtime".
 
+Deprecations
+------------
+
+- Deprecation warnings related to import of the following API functions were
+  added: ``pyramid.traversal.find_model``, ``pyramid.traversal.model_path``,
+  ``pyramid.traversal.model_path_tuple``, ``pyramid.url.model_url``.  The
+  instructions emitted by the deprecation warnings instruct the developer to
+  change these method spellings to their ``resource`` equivalents.  This is a
+  consequence of the mass concept rename of "model" to "resource" performed
+  in 1.0a7.
+
 1.0a9 (2011-01-08)
 ==================
 
diff --git a/TODO.txt b/TODO.txt
index dd0f8cff8..30dd66164 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -6,17 +6,15 @@ Must-Have (before 1.0)
 
 - Write a "Whats New" (delta from BFG 1.3)
 
-- Consider deprecations for ``model`` and ``resource`` APIs.
-
 - API docs for ``pyramid.views.action``.  (also, @action decorator uses
   ``name`` for the method name; consider whether this will be confused with
   ``name`` of ``view_config`` which means something else)
 
+- Add docs for ``__action_decorator__`` attr of handler.
+
 - Use a commit veto when configuring repoze.tm2 in paster templates for
   non-1X, 2X, or 3X responses.
 
-- Add docs for ``__action_decorator__`` attr of handler.
-
 - Figure out how to slim the herd of paster templates.
 
 - Explain i18n in Mako and Jinja2.
@@ -49,14 +47,14 @@ Should-Have
 - Provide a response_set_cookie method on the request for rendered responses
   that can be used as input to response.set_cookie?
 
-Nice-to-Have
-------------
-
 - Make it possible to get at ACLDenied data from Forbidden response in
   exceptionview.
 
-- ``config.meta`` classmethod which adds a new method to the Configurator
-  class.
+- ``config.meta`` or ``config.extend`` classmethod which adds a new method
+  ("directive") to the Configurator class.
+
+Nice-to-Have
+------------
 
 - Better "Extending" chapter.
 
diff --git a/pyramid/traversal.py b/pyramid/traversal.py
index f32b43493..f5c79dbeb 100644
--- a/pyramid/traversal.py
+++ b/pyramid/traversal.py
@@ -2,6 +2,7 @@ import urllib
 
 from zope.interface import implements
 from zope.interface.interfaces import IInterface
+from zope.deprecation import deprecated
 
 from repoze.lru import lru_cache
 
@@ -73,7 +74,8 @@ def find_resource(resource, path):
     resolved by ``find_resource``.
 
     .. note:: For backwards compatibility purposes, this function can also
-       be imported as :func:`pyramid.traversal.find_model`.
+       be imported as :func:`pyramid.traversal.find_model`, although doing so
+       will emit a deprecation warning.
     """
     D = traverse(resource, path)
     view_name = D['view_name']
@@ -84,6 +86,12 @@ def find_resource(resource, path):
 
 find_model = find_resource # b/w compat
 
+deprecated(
+    'find_model',
+    'pyramid.traversal.find_model is deprecated as of Pyramid 1.0.  Use'
+    '``pyramid.traversal.find_resource`` instead (API-compat, simple '
+    'rename).')
+
 def find_interface(resource, class_or_interface):
     """
     Return the first resource found in the :term:`lineage` of ``resource``
@@ -143,7 +151,8 @@ def resource_path(resource, *elements):
               single leading '/' character.
 
     .. note:: For backwards compatibility purposes, this function can also
-       be imported as ``model_path``.
+       be imported as ``model_path``, although doing so will cause
+       a deprecation warning to be emitted.
     """
     # joining strings is a bit expensive so we delegate to a function
     # which caches the joined result for us
@@ -151,6 +160,12 @@ def resource_path(resource, *elements):
 
 model_path = resource_path # b/w compat
 
+deprecated(
+    'model_path',
+    'pyramid.traversal.model_path is deprecated as of Pyramid 1.0.  Use'
+    '``pyramid.traversal.resource_path`` instead (API-compat, simple rename).')
+
+
 def traverse(resource, path):
     """Given a resource object as ``resource`` and a string or tuple
     representing a path as ``path`` (such as the return value of
@@ -346,14 +361,20 @@ def resource_path_tuple(resource, *elements):
               its name will be the first element in the generated
               path tuple rather than the empty string.
 
-    .. note:: For backwards compatibility purposes, this function can also
-       be imported as ``model_path_tuple``.
+    .. note:: For backwards compatibility purposes, this function can also be
+       imported as ``model_path_tuple``, although doing so will cause a
+       deprecation warning to be emitted.
 
     """
     return tuple(_resource_path_list(resource, *elements))
 
 model_path_tuple = resource_path_tuple  # b/w compat
 
+deprecated(
+    'model_path_tuple',
+    'pyramid.traversal.model_path_tuple is deprecated as of Pyramid 1.0.  Use'
+    '``pyramid.traversal.resource_path_tuple`` instead (API-compat, simple '
+    'rename).')
 
 def _resource_path_list(resource, *elements):
     """ Implementation detail shared by resource_path and resource_path_tuple"""
@@ -362,7 +383,7 @@ def _resource_path_list(resource, *elements):
     path.extend(elements)
     return path
 
-_model_path_list = _resource_path_list # b/w compat
+_model_path_list = _resource_path_list # b/w compat, not an API
 
 def virtual_root(resource, request):
     """
@@ -633,7 +654,7 @@ class ResourceTreeTraverser(object):
                 'traversed':vpath_tuple, 'virtual_root':vroot,
                 'virtual_root_path':vroot_tuple, 'root':root}
 
-ModelGraphTraverser = ResourceTreeTraverser # b/w compat
+ModelGraphTraverser = ResourceTreeTraverser # b/w compat, not API, used in wild
 
 class TraversalContextURL(object):
     """ The IContextURL adapter used to generate URLs for a resource in a
diff --git a/pyramid/url.py b/pyramid/url.py
index 3126ad26c..f2507830d 100644
--- a/pyramid/url.py
+++ b/pyramid/url.py
@@ -2,6 +2,8 @@
 
 import os
 
+from zope.deprecation import deprecated
+
 from repoze.lru import lru_cache
 
 from pyramid.interfaces import IContextURL
@@ -273,8 +275,9 @@ def resource_url(resource, request, *elements, **kw):
               virtual root prefix (it will be stripped off the
               left hand side of the generated URL).
 
-    .. note:: For backwards compatibility purposes, this function can also
-       be imported as ``model_url``.
+    .. note:: For backwards compatibility purposes, this function can also be
+       imported as ``model_url``, although doing so will emit a deprecation
+       warning.
     """
     try:
         reg = request.registry
@@ -307,6 +310,12 @@ def resource_url(resource, request, *elements, **kw):
 
 model_url = resource_url # b/w compat (forever)
 
+deprecated(
+    'model_url',
+    'pyramid.url.model_url is deprecated as of Pyramid 1.0.  Use'
+    '``pyramid.url.resource_url`` instead (API-compat, simple '
+    'rename).')
+
 def static_url(path, request, **kw):
     """
     Generates a fully qualified URL for a static :term:`asset`.