diff options
| -rw-r--r-- | docs/designdefense.rst | 131 | ||||
| -rw-r--r-- | docs/glossary.rst | 38 | ||||
| -rw-r--r-- | docs/narr/declarative.rst | 22 | ||||
| -rw-r--r-- | docs/narr/environment.rst | 2 | ||||
| -rw-r--r-- | docs/narr/handlers.rst | 4 | ||||
| -rw-r--r-- | docs/narr/introduction.rst | 15 | ||||
| -rw-r--r-- | docs/narr/project.rst | 10 | ||||
| -rw-r--r-- | docs/narr/resources.rst | 4 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 44 | ||||
| -rw-r--r-- | docs/narr/traversal.rst | 9 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 2 | ||||
| -rw-r--r-- | docs/tutorials/wiki/basiclayout.rst | 14 | ||||
| -rw-r--r-- | docs/tutorials/wiki/definingmodels.rst | 22 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/definingmodels.rst | 12 | ||||
| -rw-r--r-- | docs/zcml/forbidden.rst | 2 | ||||
| -rw-r--r-- | docs/zcml/notfound.rst | 2 | ||||
| -rw-r--r-- | docs/zcml/route.rst | 2 | ||||
| -rw-r--r-- | docs/zcml/view.rst | 6 | ||||
| -rw-r--r-- | pyramid/request.py | 2 |
19 files changed, 168 insertions, 175 deletions
diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 1a8868883..5aa149824 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -606,77 +606,48 @@ folks that haven't yet spent that 30 minutes. Pyramid Uses "Model" To Represent A Node In The Graph of Objects Traversed -------------------------------------------------------------------------- -The :app:`Pyramid` documentation refers to the graph being -traversed when :term:`traversal` is used as a "model graph". Some of -the :app:`Pyramid` APIs also use the word "model" in them when -referring to a node in this graph (e.g. ``pyramid.url.model_url``). - -A terminology overlap confuses people who write applications that -always use ORM packages such as SQLAlchemy, which has a different -notion of the definition of a "model". When using the API of common -ORM packages, its conception of "model" is almost certainly not a -directed acyclic graph (as may be the case in many graph databases). -Often model objects must be explicitly manufactured by an ORM as a -result of some query performed by a :term:`view`. As a result, it can -be unnatural to think of the nodes traversed as "model" objects if you -develop your application using traversal and a relational database. -When you develop such applications, the things that :app:`Pyramid` -refers to as "models" in such an application may just be stand-ins -that perform a query and generate some wrapper *for* an ORM "model" -(or set of ORM models). The graph *might* be composed completely of -"model" objects (as defined by the ORM) but it also might not be. - -The naming impedance mismatch between the way the term "model" is used -to refer to a node in a graph in :app:`Pyramid` and the way the -term "model" is used by packages like SQLAlchemy is unfortunate. For -the purpose of avoiding confusion, if we had it to do all over again, -we might refer to the graph that :app:`Pyramid` traverses a "node -graph" or "object graph" rather than a "model graph", but since we've -baked the name into the API, it's a little late. Sorry. - -In our defense, many :app:`Pyramid` applications (especially ones -which use :term:`ZODB`) do indeed traverse a graph full of model -nodes. Each node in the graph is a separate persistent object that is -stored within a database. This was the use case considered when -coming up with the "model" terminology. +The ``repoze.bfg`` documentation used to refer to the graph being traversed +when :term:`traversal` is used as a "model graph". A terminology overlap +confused people who wrote applications that always use ORM packages such as +SQLAlchemy, which has a different notion of the definition of a "model". As +a sresult, in Pyramid 1.0a7, the tree of objects traversed is now renamed to +:term:`resource tree` and its components are now named :term:`resource` +objects. Associated APIs have been changed. This hopefully alleviates the +terminology confusion caused by overriding the term "model". Pyramid Does Traversal, And I Don't Like Traversal -------------------------------------------------- -In :app:`Pyramid`, :term:`traversal` is the act of resolving a URL -path to a :term:`model` object in an object graph. Some people are -uncomfortable with this notion, and believe it is wrong. - -This is understandable. The people who believe it is wrong almost -invariably have all of their data in a relational database. -Relational databases aren't naturally hierarchical, so "traversing" -one like a graph is not possible. This problem is related to -:ref:`model_traversal_confusion`. - -Folks who deem traversal unilaterally "wrong" are neglecting to take -into account that many persistence mechanisms *are* hierarchical. -Examples include a filesystem, an LDAP database, a :term:`ZODB` (or -another type of graph) database, an XML document, and the Python -module namespace. It is often convenient to model the frontend to a -hierarchical data store as a graph, using traversal to apply views to -objects that either *are* the nodes in the graph being traversed (such -as in the case of ZODB) or at least ones which stand in for them (such -as in the case of wrappers for files from the filesystem). - -Also, many website structures are naturally hierarchical, even if the -data which drives them isn't. For example, newspaper websites are -often extremely hierarchical: sections within sections within -sections, ad infinitum. If you want your URLs to indicate this -structure, and the structure is indefinite (the number of nested -sections can be "N" instead of some fixed number), traversal is an -excellent way to model this, even if the backend is a relational -database. In this situation, the graph being traversed is actually -less a "model graph" than a site structure. - -But the point is ultimately moot. If you use :app:`Pyramid`, and -you don't want to model your application in terms of traversal, you -needn't use it at all. Instead, use :term:`URL dispatch` to map URL -paths to views. +In :app:`Pyramid`, :term:`traversal` is the act of resolving a URL path to a +:term:`resource` object in a resource tree. Some people are uncomfortable +with this notion, and believe it is wrong. + +This is understandable. The people who believe it is wrong almost invariably +have all of their data in a relational database. Relational databases aren't +naturally hierarchical, so "traversing" one like a tree is not possible. + +Folks who deem traversal unilaterally "wrong" are neglecting to take into +account that many persistence mechanisms *are* hierarchical. Examples +include a filesystem, an LDAP database, a :term:`ZODB` (or another type of +graph) database, an XML document, and the Python module namespace. It is +often convenient to model the frontend to a hierarchical data store as a +graph, using traversal to apply views to objects that either *are* the +resources in the tree being traversed (such as in the case of ZODB) or at +least ones which stand in for them (such as in the case of wrappers for files +from the filesystem). + +Also, many website structures are naturally hierarchical, even if the data +which drives them isn't. For example, newspaper websites are often extremely +hierarchical: sections within sections within sections, ad infinitum. If you +want your URLs to indicate this structure, and the structure is indefinite +(the number of nested sections can be "N" instead of some fixed number), a +resource tree is an excellent way to model this, even if the backend is a +relational database. In this situation, the resource tree a just a site +structure. + +But the point is ultimately moot. If you use :app:`Pyramid`, and you don't +want to model your application in terms of a resource tree, you needn't use +it at all. Instead, use :term:`URL dispatch` to map URL paths to views. Pyramid Does URL Dispatch, And I Don't Like URL Dispatch -------------------------------------------------------- @@ -705,7 +676,7 @@ top of your object graph (or any administrative interface), you can register a route like ``<route name="manage" pattern="manage/*traverse"/>`` and then associate "management" views in your code by using the ``route_name`` argument to a ``view`` configuration, e.g. ``<view view=".some.callable" -context=".some.Model" route_name="manage"/>``. If you wire things up this +context=".some.Resource" route_name="manage"/>``. If you wire things up this way someone then walks up to for example, ``/manage/ob1/ob2``, they might be presented with a management interface, but walking up to ``/ob1/ob2`` would present them with the default object view. There are other tricks you can @@ -745,7 +716,7 @@ which match information in an associated "urlconf" such as return HttpResponse(poll_id) Zope, likewise allows you to add arbitrary keyword and positional -arguments to any method of a model object found via traversal: +arguments to any method of a resource object found via traversal: .. ignore-next-block .. code-block:: python @@ -993,14 +964,16 @@ frameworks have some sort of event system hooked up that lets the view detect when the model changes. The web just has no such facility in its current form: it's effectively pull-only. -So, in the interest of not mistaking desire with reality, and instead -of trying to jam the square peg that is the web into the round hole of -"MVC", we just punt and say there are two things: the model, and the -view. The model stores the data, the view presents it. The templates -are really just an implementation detail of any given view: a view -doesn't need a template to return a response. There's no -"controller": it just doesn't exist. This seems to us like a more -reasonable model, given the current constraints of the web. +So, in the interest of not mistaking desire with reality, and instead of +trying to jam the square peg that is the web into the round hole of "MVC", we +just punt and say there are two things: resources and views. The resource +tree represents a site structure, the view presents a resource. The +templates are really just an implementation detail of any given view: a view +doesn't need a template to return a response. There's no "controller": it +just doesn't exist. The "model" is either represented by the resource tree +or by a "domain model" (like a SQLAlchemy model) that is separate from the +framework entirely. This seems to us like more reasonable terminology, given +the current constraints of the web. .. _apps_are_extensible: @@ -1151,9 +1124,9 @@ access. I like this, because it means: permissions that the accessing user possesses with respect to a context object. -#) I want to also expose my model via a REST API using Twisted Web. If +#) I want to also expose my resources via a REST API using Twisted Web. If Pyramid performed authorization based on attribute access via Zope3's - security proies, I could enforce my authorization policy in both + security proxies, I could enforce my authorization policy in both :app:`Pyramid` and in the Twisted-based system the same way. Defense diff --git a/docs/glossary.rst b/docs/glossary.rst index 68d89d381..a27d73766 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -49,7 +49,7 @@ Glossary a Python source code file. asset specification - A colon-delimited identifier for a :term:`resource`. The colon + A colon-delimited identifier for an :term:`asset`. The colon separates a Python :term:`package` name from a package subpath. For example, the asset specification ``my.package:static/baz.css`` identifies the file named @@ -120,10 +120,10 @@ Glossary string (which implies the :term:`default view`). Default view - The default view of a resource is the view invoked when the - :term:`view name` is the empty string (``''``). This is the case - when :term:`traversal` exhausts the path elements in the PATH_INFO - of a request before it returns a :term:`context`. + The default view of a :term:`resource` is the view invoked when the + :term:`view name` is the empty string (``''``). This is the case when + :term:`traversal` exhausts the path elements in the PATH_INFO of a + request before it returns a :term:`context`. virtualenv An isolated Python environment. Allows you to control which @@ -132,15 +132,24 @@ Glossary was created by Ian Bicking. resource - An object representing a node in the resource tree of an application. - If :mod:`traversal` is used, a resource is an element in the resource - tree traversed by the system. When traversal is used, a resource - becomes the :term:`context` of a :term:`view`. If :mod:`url dispatch` - is used, a single resource is generated for each request and is - used as the context of a view. + An object representing a node in the :term:`resource tree` of an + application. If :mod:`traversal` is used, a resource is an element in + the resource tree traversed by the system. When traversal is used, a + resource becomes the :term:`context` of a :term:`view`. If :mod:`url + dispatch` is used, a single resource is generated for each request and + is used as the context of a view. + + resource tree + A nested set of dictionary-like objects, each of which is a + :term:`resource`. The act of :term:`traversal` uses the resource tree + to find a :term:`context`. + + domain model + Persistent data related to your application. For example, data stored + in a relational database. In some applications, the :term:`resource + tree` acts as the domain model. traversal - The act of descending "up" a tree of resource objects from a root resource in order to find a :term:`context`. The :app:`Pyramid` :term:`router` performs traversal of resource objects when a :term:`root @@ -188,8 +197,9 @@ Glossary text, XML, or HTML when rendered. location - The path to an object in a resource tree. See :ref:`location_aware` for - more information about how to make a resource object *location-aware*. + The path to an object in a :term:`resource tree`. See + :ref:`location_aware` for more information about how to make a resource + object *location-aware*. permission A string or unicode object that represents an action being taken against diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index 54e9ecaa1..28dec4ff1 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -720,19 +720,19 @@ documentation. .. index:: triple: view; zcml; static resource -.. _zcml_static_resources_section: +.. _zcml_static_assets_section: -Serving Static Resources Using ZCML ------------------------------------- +Serving Static Assets Using ZCML +-------------------------------- -Use of the ``static`` ZCML directive makes static files available at a name -relative to the application root URL, e.g. ``/static``. +Use of the ``static`` ZCML directive makes static assets available at a name +relative to the application root URL, e.g. ``/static``. Note that the ``path`` provided to the ``static`` ZCML directive may be a -fully qualified :term:`resource specification`, a package-relative path, or +fully qualified :term:`asset specification`, a package-relative path, or an *absolute path*. The ``path`` with the value ``a/b/c/static`` of a ``static`` directive in a ZCML file that resides in the "mypackage" package -will resolve to a package-qualified resource such as +will resolve to a package-qualified assets such as ``some_package:a/b/c/static``. Here's an example of a ``static`` ZCML directive that will serve files @@ -751,7 +751,7 @@ absolute path. Here's an example of a ``static`` directive that will serve files up under the ``/static`` URL from the ``a/b/c/static`` directory of the Python package named ``some_package`` using a fully qualified -:term:`resource specification`. +:term:`asset specification`. .. code-block:: xml :linenos: @@ -774,7 +774,7 @@ package-relative path. path="static" /> -Whether you use for ``path`` a fully qualified resource specification, +Whether you use for ``path`` a fully qualified asset specification, an absolute path, or a package-relative path, When you place your static files on the filesystem in the directory represented as the ``path`` of the directive, you will then be able to view the static @@ -791,7 +791,7 @@ While the ``path`` argument can be a number of different things, the ``name`` argument of the ``static`` ZCML directive can also be one of a number of things: a *view name* or a *URL*. The above examples have shown usage of the ``name`` argument as a view name. When ``name`` is -a *URL* (or any string with a slash (``/``) in it), static resources +a *URL* (or any string with a slash (``/``) in it), static assets can be served from an external webserver. In this mode, the ``name`` is used as the URL prefix when generating a URL using :func:`pyramid.url.static_url`. @@ -819,7 +819,7 @@ detail later in this chapter. The :meth:`pyramid.config.Configurator.add_static_view` method offers an imperative equivalent to the ``static`` ZCML directive. Use of the ``add_static_view`` imperative configuration method is completely equivalent -to using ZCML for the same purpose. See :ref:`static_resources_section` for +to using ZCML for the same purpose. See :ref:`static_assets_section` for more information. .. index:: diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 8cad9a666..0c6f3dd03 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -61,7 +61,7 @@ also :ref:`overriding_assets_section`. +---------------------------------+-----------------------------+ | Environment Variable Name | Config File Setting Name | +=================================+=============================+ -| ``BFG_RELOAD_ASSETS` ` | ``reload_assets`` | +| ``BFG_RELOAD_ASSETS`` | ``reload_assets`` | | | | | | | | | | diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst index f6e658cf0..5b6f71984 100644 --- a/docs/narr/handlers.rst +++ b/docs/narr/handlers.rst @@ -100,7 +100,7 @@ Using :meth:`~pyramid.config.Configurator.add_handler` When calling :meth:`~pyramid.config.Configurator.add_handler`, an ``action`` is required in either the route pattern or as a keyword argument, but **cannot appear in both places**. A ``handler`` argument must also be -supplied, which can be either a :term:`resource specification` or a Python +supplied, which can be either a :term:`asset specification` or a Python reference to the handler class. Additional keyword arguments are passed directly through to :meth:`pyramid.config.Configurator.add_route`. @@ -112,7 +112,7 @@ For example: config.add_handler('hello', '/hello/{action}', handler='mypackage.handlers:MyHandler') -In larger applications, it is advised to use a :term:`resource specification` +In larger applications, it is advised to use a :term:`asset specification` with :meth:`~pyramid.config.Configurator.add_handler` to avoid having to import every handler class. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 0d8077fc4..3ade3726c 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -178,10 +178,11 @@ frameworks, :app:`Pyramid` also generally fits into this class. The :app:`Pyramid` authors believe that the MVC pattern just doesn't really fit the web very well. In a :app:`Pyramid` application, there is a - model, which stores data, and views, which present the data stored in the - model. However, no facility provided by the framework actually maps to - the concept of a "controller". So :app:`Pyramid` is actually an "MV" - framework rather than an "MVC" framework. "MVC", however, is close enough - as a general classification moniker for purposes of comparison with other - web frameworks. - + resource tree, which represents the site structure, and views, which tend + to present the data stored in the resource tree and a user-defined "domain + model". However, no facility provided *by the framework* actually + necessarily maps to the concept of a "controller" or "model". So if you + had to give it some acronym, I guess you'd say :app:`Pyramid` is actually + an "RV" framework rather than an "MVC" framework. "MVC", however, is + close enough as a general classification moniker for purposes of + comparison with other web frameworks. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 27974d8df..ff03a57b8 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -790,13 +790,13 @@ also informs Python that the directory which contains it is a *package*. name`. The view declaration also names a ``renderer``, which in this case is a template that will be used to render the result of the view callable. This particular view declaration points at - ``myproject:templates/mytemplate.pt``, which is a :term:`resource + ``myproject:templates/mytemplate.pt``, which is a :term:`asset specification` that specifies the ``mytemplate.pt`` file within the ``templates`` directory of the ``myproject`` package. The template file it actually points to is a :term:`Chameleon` ZPT template file. Line 11 registers a static view, which will serve up the files from the - ``mypackage:static`` :term:`resource specification` (the ``static`` + ``mypackage:static`` :term:`asset specification` (the ``static`` directory of the ``mypackage`` package). Line 12 returns a :term:`WSGI` application to the caller of the function @@ -874,10 +874,10 @@ sort of datastore you'll want to use, so the sample application uses an instance of :class:`myproject.resources.Root` to represent the root. ``static`` -~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~ -This directory contains static resources which support the -``mytemplate.pt`` template. It includes CSS and images. +This directory contains static assets which support the ``mytemplate.pt`` +template. It includes CSS and images. .. index:: single: tests.py diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 05e108494..21ba97c9e 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -3,7 +3,7 @@ Resources A :term:`resource` is an object that represents a "place" in your application. Every :app:`Pyramid` application has at least one resource -object: the :term:`root resource`. The root resource is the root of a +object: the :term:`root` resource. The root resource is the root of a :term:`resource tree`. A resource tree is a set of nested dictionary-like objects which you may use to represent your website's structure. @@ -25,7 +25,7 @@ that use traversal. In "Zope-like" :app:`Pyramid` applications, resource objects also often store data persistently and offer methods related to mutating that persistent data. In these kinds of applications, resources not only represent the site -structure of your website, but they become the :term:`model` of the +structure of your website, but they become the :term:`domain model` of the application. Also: diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index d6c21831e..adec9aa0c 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -84,9 +84,9 @@ prefix on Windows. file instead of treating relative paths as relative to the current view module. See :ref:`mako_templates`. -The path can alternately be a :term:`resource specification` in the form +The path can alternately be a :term:`asset specification` in the form ``some.dotted.package_name:relative/path``. This makes it possible to -address template resources which live in another package. For example: +address template assets which live in another package. For example: .. code-block:: python :linenos: @@ -98,20 +98,20 @@ address template resources which live in another package. For example: {'foo':1, 'bar':2}, request=request) -A resource specification points at a file within a Python *package*. +An asset specification points at a file within a Python *package*. In this case, it points at a file named ``foo.pt`` within the ``templates`` directory of the ``mypackage`` package. Using a -resource specification instead of a relative template name is usually -a good idea, because calls to ``render_to_response`` using resource +asset specification instead of a relative template name is usually +a good idea, because calls to ``render_to_response`` using asset specifications will continue to work properly if you move the code containing them around. .. note:: - Mako templating system bindings also respect absolute resource + Mako templating system bindings also respect absolute asset specifications as an argument to any of the ``render*`` commands. If a template name defines a ``:`` (colon) character and is not an absolute - path, it is treated as an absolute resource specification. + path, it is treated as an absolute asset specification. In the examples above we pass in a keyword argument named ``request`` representing the current :app:`Pyramid` request. Passing a request @@ -187,8 +187,8 @@ combination as shown above. :app:`Pyramid` bindings directly within view callables, the auto-template-reload strategy explained in :ref:`reload_templates_section` will not be available, nor will the - template resource overriding capability explained in - :ref:`overriding_resources_section` be available, nor will it be + template asset overriding capability explained in + :ref:`overriding_assets_section` be available, nor will it be possible to use any template using that language as a :term:`renderer`. However, it's reasonably easy to write custom templating system binding packages for use under :app:`Pyramid` so @@ -289,7 +289,7 @@ to specify the template as a :term:`renderer` in your templating languages supported by :app:`Pyramid`. To use a renderer via view configuration, specify a template -:term:`resource specification` as the ``renderer`` argument, or +:term:`asset specification` as the ``renderer`` argument, or attribute to the :term:`view configuration` of a :term:`view callable`. Then return a *dictionary* from that view callable. The dictionary items returned by the view callable will be made available @@ -326,7 +326,7 @@ template renderer: we're using a Chameleon renderer, it means "relative to the directory in which the file which defines the view configuration lives". In this case, this is the directory containing the file that defines the ``my_view`` - function. View-configuration-relative resource specifications work only + function. View-configuration-relative asset specifications work only in Chameleon, not in Mako templates. Similar renderer configuration can be done imperatively and via @@ -335,9 +335,9 @@ Similar renderer configuration can be done imperatively and via Although a renderer path is usually just a simple relative pathname, a path named as a renderer can be absolute, starting with a slash on UNIX or a drive -letter prefix on Windows. The path can alternately be a :term:`resource +letter prefix on Windows. The path can alternately be an :term:`asset specification` in the form ``some.dotted.package_name:relative/path``, making -it possible to address template resources which live in another package. +it possible to address template assets which live in another package. Not just any template from any arbitrary templating system may be used as a renderer. Bindings must exist specifically for :app:`Pyramid` to use a @@ -473,15 +473,15 @@ least two top-level names available to the template by default: ``context`` and ``request``. One of the common needs in ZPT-based templates is to use one template's "macros" from within a different template. In Zope, this is typically handled by retrieving the template from the ``context``. But the -context in :app:`Pyramid` is a resource object, and templates cannot usually -be retrieved from resources. To use macros in :app:`Pyramid`, you need to make -the macro template itself available to the rendered template by passing the -macro template, or even the macro itself, *into* the rendered template. To -do this you can use the :func:`pyramid.renderers.get_renderer` API to -retrieve the macro template, and pass it into the template being rendered via -the dictionary returned by the view. For example, using a :term:`view -configuration` via a :class:`pyramid.view.view_config` decorator that uses a -:term:`renderer`: +context in :app:`Pyramid` is a :term:`resource` object, and templates cannot +usually be retrieved from resources. To use macros in :app:`Pyramid`, you +need to make the macro template itself available to the rendered template by +passing the macro template, or even the macro itself, *into* the rendered +template. To do this you can use the :func:`pyramid.renderers.get_renderer` +API to retrieve the macro template, and pass it into the template being +rendered via the dictionary returned by the view. For example, using a +:term:`view configuration` via a :class:`pyramid.view.view_config` decorator +that uses a :term:`renderer`: .. code-block:: python :linenos: diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index c8878224e..9bc6014cd 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -223,9 +223,12 @@ root factory always returns an object that has no child resources. availability is more useful when you're developing an application using :term:`URL dispatch`. -Items contained within the resource tree are sometimes, in certain types of -applications, analogous to the concept of :term:`model` objects used by many -other frameworks. They are typically instances of Python classes. +.. note:: + + If the items contained within the resource tree are "persistent" (they + have state that lasts longer than the execution of a single process), they + become analogous to the concept of :term:`domain model` objects used by + many other frameworks. The resource tree consists of *container* resources and *leaf* resources. There is only one difference between a *container* resource and a *leaf* diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 8adeb2511..739a826c1 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -613,7 +613,7 @@ represent neither predicates nor view configuration information. ``view_renderer`` This is either a single string term (e.g. ``json``) or a string - implying a path or :term:`resource specification` + implying a path or :term:`asset specification` (e.g. ``templates/views.pt``). If the renderer value is a single term (does not contain a dot ``.``), the specified term will be used to look up a renderer implementation, and that renderer diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 3dbf10bd8..c7c722f70 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -98,11 +98,15 @@ following: Content Models with ``models.py`` --------------------------------- -:app:`Pyramid` often uses the word :term:`model` when talking about -content resources arranged in the hierarchical *object graph* -consulted by :term:`traversal`. The ``models.py`` file is where the -``pyramid_zodb`` Paster template put the classes that implement our -model objects. +:app:`Pyramid` uses the word :term:`resource` to describe objects arranged +hierarchically in a :term:`resource tree`. This tree is consulted by +:term:`traversal` to map URLs to code. In this application, the resource +tree represents the site structure, but it *also* represents the +:term:`domain model` of the application, because eeach resource is a node +stored persistently in a :term:`ZODB` database. The ``models.py`` file is +where the ``pyramid_zodb`` Paster template put the classes that implement our +resource objects, each of which happens also to be a domain model +object. Here is the source for ``models.py``: diff --git a/docs/tutorials/wiki/definingmodels.rst b/docs/tutorials/wiki/definingmodels.rst index 097485047..f317d31dd 100644 --- a/docs/tutorials/wiki/definingmodels.rst +++ b/docs/tutorials/wiki/definingmodels.rst @@ -1,15 +1,17 @@ -=============== -Defining Models -=============== +========================= +Defining the Domain Model +========================= The first change we'll make to our bone-stock ``paster`` -generated -application will be to define a number of :term:`model` constructors. -For this application, which will be a Wiki, we will need two kinds of -model constructors: a "Wiki" model constructor, and a "Page" model -constructor. Both our Page and Wiki constructors will be class -objects. A single instance of the "Wiki" class will serve as a -container for "Page" objects, which will be instances of the "Page" -class. +application will be to define a number of :term:`resource` constructors. +Remember that, because we're using :term:`ZODB` to represent our +:term:`resource tree`, each of these resource constructors represents a +:term:`domain model` object, so we'll call these constructors "model +constructors". For this application, which will be a Wiki, we will need two +kinds of model constructors: a "Wiki" model constructor, and a "Page" model +constructor. Both our Page and Wiki constructors will be class objects. A +single instance of the "Wiki" class will serve as a container for "Page" +objects, which will be instances of the "Page" class. The source code for this tutorial stage can be browsed via `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/models/ diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index b710e1396..d07ac1055 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -1,10 +1,10 @@ -=============== -Defining Models -=============== +======================= +Defining a Domain Model +======================= -The first change we'll make to our stock paster-generated application -will be to define a :term:`model` constructor representing a wiki -page. We'll do this inside our ``models.py`` file. +The first change we'll make to our stock paster-generated application will be +to define a :term:`domain model` constructor representing a wiki page. We'll +do this inside our ``models.py`` file. The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/models/ diff --git a/docs/zcml/forbidden.rst b/docs/zcml/forbidden.rst index 7ea6b85fd..70f65069e 100644 --- a/docs/zcml/forbidden.rst +++ b/docs/zcml/forbidden.rst @@ -35,7 +35,7 @@ Attributes ``renderer`` This is either a single string term (e.g. ``json``) or a string - implying a path or :term:`resource specification` + implying a path or :term:`asset specification` (e.g. ``templates/views.pt``) used when the view returns a non-:term:`response` object. This attribute has the same meaning as it would in the context of :ref:`view_directive`; see the diff --git a/docs/zcml/notfound.rst b/docs/zcml/notfound.rst index a2ed95bc4..739eccd49 100644 --- a/docs/zcml/notfound.rst +++ b/docs/zcml/notfound.rst @@ -34,7 +34,7 @@ Attributes ``renderer`` This is either a single string term (e.g. ``json``) or a string - implying a path or :term:`resource specification` + implying a path or :term:`asset specification` (e.g. ``templates/views.pt``) used when the view returns a non-:term:`response` object. This attribute has the same meaning as it would in the context of :ref:`view_directive`; see the diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst index ac9261e27..0f94fa11b 100644 --- a/docs/zcml/route.rst +++ b/docs/zcml/route.rst @@ -172,7 +172,7 @@ Attributes ``view_renderer`` This is either a single string term (e.g. ``json``) or a string - implying a path or :term:`resource specification` + implying a path or :term:`asset specification` (e.g. ``templates/views.pt``). If the renderer value is a single term (does not contain a dot ``.``), the specified term will be used to look up a renderer implementation, and that renderer diff --git a/docs/zcml/view.rst b/docs/zcml/view.rst index 6887f88fb..b4fabdc2c 100644 --- a/docs/zcml/view.rst +++ b/docs/zcml/view.rst @@ -51,7 +51,7 @@ Non-Predicate Attributes ``renderer`` This is either a single string term (e.g. ``json``) or a string - implying a path or :term:`resource specification` + implying a path or :term:`asset specification` (e.g. ``templates/views.pt``). If the renderer value is a single term (does not contain a dot ``.``), the specified term will be used to look up a renderer implementation, and that renderer @@ -72,10 +72,10 @@ Non-Predicate Attributes template named "foo.pt" is in the "templates" directory relative to the directory in which the ZCML file is defined), a path can be absolute, starting with a slash on UNIX or a drive letter prefix on - Windows. The path can alternately be a :term:`resource + Windows. The path can alternately be a :term:`asset specification` in the form ``some.dotted.package_name:relative/path``, making it possible to - address template resources which live in a separate package. + address template assets which live in a separate package. The ``renderer`` attribute is optional. If it is not defined, the "null" renderer is assumed (no rendering is performed and the value diff --git a/pyramid/request.py b/pyramid/request.py index a2dafc5e0..74418f1bb 100644 --- a/pyramid/request.py +++ b/pyramid/request.py @@ -221,7 +221,7 @@ class Request(WebobRequest): resource_url(resource, request) .. note:: For backwards compatibility purposes, this method can also - be called as :meth:`pyramid.request.Request.model_url`. + be called as :meth:`pyramid.request.Request.model_url`. """ return resource_url(resource, self, *elements, **kw) |