Repository: Pylons/pyramid

Issue:
Rewrite docs for "Custom Route Predicates"
The section "Custom Route Predicates" in narr/urldispatch.rst still uses the (as of 1.5) deprecated method of adding route predicates via `add_route/add_view(custom_predicates=...)`. It should be rewritten to use the new `Configurator.add_view_predicate`/`Configurator.add_route_predicate`.



Discussion:
Can you submit a PR with proposed changes? That will get this issue resolved much faster.

That's what I'm about to do. I mostly added the issue as a todo for me and as a reminder for others that it exists. 

But: the section is pretty long and it's not just a task of search/replace. I really have to look into how the new stuff works and where it fits into the docs. May be the current place won't be the correct one for the rewritten paragraph. 

@hellp Have you gotten any further on this?

Uh, no, completely lost track of it. You wanna work on it? I could look if I still have a draft lying around or so. Not sure.

I took a look, and I am too dense to understand the big words. I've unassigned myself from this issue.

That said, I did find the following reference that perhaps could replace the current section entirely?
https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/hooks.html#registering-thirdparty-predicates
Per [discussion in IRC](https://botbot.me/freenode/pyramid/2018-09-10/?msg=104212118&page=2), my guess is the proper direction.
Removed from 1.10 milestone.
I was about to report this, having found no deprecation notice in https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/viewconfig.html#view-configuration-parameters (sorry can’t link to exact section — another possible improvement) and only noticing when running pserve with Python warnings enabled.  I may tackle it after #3520 

Seems related to #3347 but that ticket has no info or links to commits.
#3347 is a duplicate of this issue.
@merwok would you like to take on this issue?
Yes, in a week or two.
PR will be here tomorrow.

Resolving patch:
diff --git a/src/pyramid/config/routes.py b/src/pyramid/config/routes.py
--- a/src/pyramid/config/routes.py
+++ b/src/pyramid/config/routes.py
@@ -40,13 +40,10 @@ def add_route(
         inherit_slash=None,
         **predicates
     ):
-        """ Add a :term:`route configuration` to the current
-        configuration state, as well as possibly a :term:`view
-        configuration` to be used to specify a :term:`view callable`
-        that will be invoked when this route matches.  The arguments
-        to this method are divided into *predicate*, *non-predicate*,
-        and *view-related* types.  :term:`Route predicate` arguments
-        narrow the circumstances in which a route will be match a
+        """ Add a :term:`route configuration` to the current configuration
+        state.  Arguments to ``add_route`` are divided into *predicate*
+        and *non-predicate* types.  :term:`Route predicate` arguments
+        narrow the circumstances in which a route will match a
         request; non-predicate arguments are informational.
 
         Non-Predicate Arguments
@@ -283,6 +280,8 @@ def add_route(
 
           .. versionadded:: 1.4a4
 
+          .. deprecated:: 2.0
+
         custom_predicates
 
           .. deprecated:: 1.5
@@ -302,14 +301,13 @@ def add_route(
               :ref:`custom_route_predicates` for more information about
               ``info``.
 
-        predicates
+        \\*\\*predicates
 
-          Pass a key/value pair here to use a third-party predicate
-          registered via
+          Pass extra keyword parameters to use custom predicates registered via
           :meth:`pyramid.config.Configurator.add_route_predicate`.  More than
-          one key/value pair can be used at the same time.  See
+          one custom predicate can be used at the same time.  See
           :ref:`view_and_route_predicates` for more information about
-          third-party predicates.
+          custom predicates.
 
           .. versionadded:: 1.4
 
@@ -321,7 +319,7 @@ def add_route(
                     'Configurator.add_route is deprecated as of Pyramid 1.5. '
                     'Use "config.add_route_predicate" and use the registered '
                     'route predicate as a predicate argument to add_route '
-                    'instead. See "Adding A Third Party View, Route, or '
+                    'instead. See "Adding A Custom View, Route, or '
                     'Subscriber Predicate" in the "Hooks" chapter of the '
                     'documentation for more information.'
                 ),
diff --git a/src/pyramid/config/views.py b/src/pyramid/config/views.py
--- a/src/pyramid/config/views.py
+++ b/src/pyramid/config/views.py
@@ -723,31 +723,30 @@ def wrapper(context, request):
 
           .. versionadded:: 1.4a4
 
+          .. deprecated:: 2.0
+
         custom_predicates
 
             .. deprecated:: 1.5
                 This value should be a sequence of references to custom
-                predicate callables.  Use custom predicates when no set of
-                predefined predicates do what you need.  Custom predicates
-                can be combined with predefined predicates as necessary.
-                Each custom predicate callable should accept two arguments:
+                predicate callables.  Each custom predicate callable
+                should accept two arguments:
                 ``context`` and ``request`` and should return either
                 ``True`` or ``False`` after doing arbitrary evaluation of
-                the context and/or the request.  The ``predicates`` argument
-                to this method and the ability to register third-party view
-                predicates via
+                the context and/or the request.  The ability to register
+                custom view predicates via
                 :meth:`pyramid.config.Configurator.add_view_predicate`
                 obsoletes this argument, but it is kept around for backwards
                 compatibility.
 
-        view_options
+        \\*\\*view_options
 
-          Pass a key/value pair here to use a third-party predicate or set a
-          value for a view deriver. See
+          Pass extra keyword parameters to use custom predicates
+          or set a value for a view deriver. See
           :meth:`pyramid.config.Configurator.add_view_predicate` and
           :meth:`pyramid.config.Configurator.add_view_deriver`. See
           :ref:`view_and_route_predicates` for more information about
-          third-party predicates and :ref:`view_derivers` for information
+          custom predicates and :ref:`view_derivers` for information
           about view derivers.
 
           .. versionadded: 1.4a1
@@ -769,7 +768,7 @@ def wrapper(context, request):
                     'Configurator.add_view is deprecated as of Pyramid 1.5. '
                     'Use "config.add_view_predicate" and use the registered '
                     'view predicate as a predicate argument to add_view '
-                    'instead. See "Adding A Third Party View, Route, or '
+                    'instead. See "Adding A Custom View, Route, or '
                     'Subscriber Predicate" in the "Hooks" chapter of the '
                     'documentation for more information.'
                 ),


Test patch: