From 92c3e502494714884b7a051721c9b322027369a1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 18 Dec 2010 03:33:35 -0500 Subject: resource -> asset --- docs/api/config.rst | 2 +- docs/api/request.rst | 2 +- docs/api/traversal.rst | 6 +- docs/api/url.rst | 2 +- docs/narr/environment.rst | 88 +++---- docs/zcml/aclauthorizationpolicy.rst | 2 +- docs/zcml/asset.rst | 65 +++++ docs/zcml/handler.rst | 2 +- docs/zcml/resource.rst | 62 ----- docs/zcml/route.rst | 2 +- docs/zcml/view.rst | 6 +- pyramid/config.py | 40 +-- pyramid/includes/meta.zcml | 2 +- pyramid/mako_templating.py | 23 +- pyramid/renderers.py | 34 +-- pyramid/request.py | 3 + pyramid/resource.py | 212 +--------------- pyramid/settings.py | 12 +- pyramid/static.py | 4 +- pyramid/tests/test_asset.py | 451 ++++++++++++++++++++++++++++++++++ pyramid/tests/test_config.py | 30 +-- pyramid/tests/test_mako_templating.py | 14 +- pyramid/tests/test_renderers.py | 8 +- pyramid/tests/test_request.py | 4 +- pyramid/tests/test_resource.py | 451 ---------------------------------- pyramid/tests/test_traversal.py | 282 ++++++++++----------- pyramid/tests/test_url.py | 8 +- pyramid/tests/test_zcml.py | 8 +- pyramid/traversal.py | 10 + pyramid/url.py | 12 +- pyramid/zcml.py | 19 +- 31 files changed, 840 insertions(+), 1026 deletions(-) create mode 100644 docs/zcml/asset.rst delete mode 100644 docs/zcml/resource.rst create mode 100644 pyramid/tests/test_asset.py delete mode 100644 pyramid/tests/test_resource.py diff --git a/docs/api/config.rst b/docs/api/config.rst index 64dc4d0dd..4b23f3e8e 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -78,7 +78,7 @@ .. automethod:: testing_securitypolicy - .. automethod:: testing_models + .. automethod:: testing_resources .. automethod:: testing_add_subscriber diff --git a/docs/api/request.rst b/docs/api/request.rst index acd66ccf8..13b434a51 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -26,7 +26,7 @@ .. attribute:: root The :term:`root` object will be available as the ``root`` - attribute of the :term:`request` object. It will be the model + attribute of the :term:`request` object. It will be the resource object at which traversal started (the root). See :ref:`traversal_chapter` for information about root objects. diff --git a/docs/api/traversal.rst b/docs/api/traversal.rst index b89691847..cd4765e04 100644 --- a/docs/api/traversal.rst +++ b/docs/api/traversal.rst @@ -7,13 +7,13 @@ .. autofunction:: find_interface - .. autofunction:: find_model + .. autofunction:: find_resource .. autofunction:: find_root - .. autofunction:: model_path + .. autofunction:: resource_path - .. autofunction:: model_path_tuple + .. autofunction:: resource_path_tuple .. autofunction:: quote_path_segment diff --git a/docs/api/url.rst b/docs/api/url.rst index 8c702a3fb..1aa3082b7 100644 --- a/docs/api/url.rst +++ b/docs/api/url.rst @@ -5,7 +5,7 @@ .. automodule:: pyramid.url - .. autofunction:: pyramid.url.model_url(context, request, *elements, query=None, anchor=None) + .. autofunction:: pyramid.url.resource_url(context, request, *elements, query=None, anchor=None) .. autofunction:: route_url diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 08fa7af44..8cad9a666 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -3,7 +3,7 @@ single: settings single: reload single: debug_authorization - single: reload_resources + single: reload_assets single: debug_notfound single: debug_all single: reload_all @@ -52,21 +52,25 @@ template rendering extensions. | | | +---------------------------------+-----------------------------+ -Reloading Resources -------------------- +Reloading Assets +---------------- -Don't cache any resource file data when this value is true. See -also :ref:`overriding_resources_section`. +Don't cache any asset file data when this value is true. See +also :ref:`overriding_assets_section`. +---------------------------------+-----------------------------+ | Environment Variable Name | Config File Setting Name | +=================================+=============================+ -| ``BFG_RELOAD_RESOURCES`` | ``reload_resources`` | +| ``BFG_RELOAD_ASSETS` ` | ``reload_assets`` | | | | | | | | | | +---------------------------------+-----------------------------+ +.. note:: For backwards compatibility purposes, the following aliases can be + used for configurating asset reloading: ``BFG_RELOAD_RESOURCES`` (envvar) + and ``reload_resources`` (config file). + Debugging Authorization ----------------------- @@ -174,7 +178,7 @@ Mako Directories ++++++++++++++++ The value(s) supplied here are passed in as the template directories. They -should be in :term:`resource specification` format, for example: +should be in :term:`asset specification` format, for example: ``my.package:templates``. +-----------------------------+ @@ -333,40 +337,38 @@ affect settings that do not start with ``reload_*`` such as .. index:: single: reload_templates - single: reload_resources - -Understanding the Distinction Between ``reload_templates`` and ``reload_resources`` ------------------------------------------------------------------------------------ - -The difference between ``reload_resources`` and ``reload_templates`` -is a bit subtle. Templates are themselves also treated by -:app:`Pyramid` as :term:`pkg_resources` resource files (along with -static files and other resources), so the distinction can be -confusing. It's helpful to read :ref:`overriding_resources_section` -for some context about resources in general. - -When ``reload_templates`` is true, :app:`Pyramid` takes advantage -of the underlying templating systems' ability to check for file -modifications to an individual template file. When -``reload_templates`` is true but ``reload_resources`` is *not* true, -the template filename returned by pkg_resources is cached by -:app:`Pyramid` on the first request. Subsequent requests for the -same template file will return a cached template filename. The -underlying templating system checks for modifications to this -particular file for every request. Setting ``reload_templates`` to -``True`` doesn't affect performance dramatically (although it should -still not be used in production because it has some effect). - -However, when ``reload_resources`` is true, :app:`Pyramid` will not -cache the template filename, meaning you can see the effect of -changing the content of an overridden resource directory for templates -without restarting the server after every change. Subsequent requests -for the same template file may return different filenames based on the -current state of overridden resource directories. Setting -``reload_resources`` to ``True`` affects performance *dramatically*, -slowing things down by an order of magnitude for each template -rendering. However, it's convenient to enable when moving files -around in overridden resource directories. ``reload_resources`` makes -the system *very slow* when templates are in use. Never set -``reload_resources`` to ``True`` on a production system. + single: reload_assets + +Understanding the Distinction Between ``reload_templates`` and ``reload_assets`` +-------------------------------------------------------------------------------- + +The difference between ``reload_assets`` and ``reload_templates`` is a bit +subtle. Templates are themselves also treated by :app:`Pyramid` as asset +files (along with other static files), so the distinction can be confusing. +It's helpful to read :ref:`overriding_assets_section` for some context +about assets in general. + +When ``reload_templates`` is true, :app:`Pyramid` takes advantage of the +underlying templating systems' ability to check for file modifications to an +individual template file. When ``reload_templates`` is true but +``reload_assets`` is *not* true, the template filename returned by the +``pkg_resources`` package (used under the hood by asset resolution) is cached +by :app:`Pyramid` on the first request. Subsequent requests for the same +template file will return a cached template filename. The underlying +templating system checks for modifications to this particular file for every +request. Setting ``reload_templates`` to ``True`` doesn't affect performance +dramatically (although it should still not be used in production because it +has some effect). + +However, when ``reload_assets`` is true, :app:`Pyramid` will not cache the +template filename, meaning you can see the effect of changing the content of +an overridden asset directory for templates without restarting the server +after every change. Subsequent requests for the same template file may +return different filenames based on the current state of overridden asset +directories. Setting ``reload_assets`` to ``True`` affects performance +*dramatically*, slowing things down by an order of magnitude for each +template rendering. However, it's convenient to enable when moving files +around in overridden asset directories. ``reload_assets`` makes the system +*very slow* when templates are in use. Never set ``reload_assets`` to +``True`` on a production system. diff --git a/docs/zcml/aclauthorizationpolicy.rst b/docs/zcml/aclauthorizationpolicy.rst index 2c66da0c8..f09531415 100644 --- a/docs/zcml/aclauthorizationpolicy.rst +++ b/docs/zcml/aclauthorizationpolicy.rst @@ -4,7 +4,7 @@ -------------------------- When this directive is used, authorization information is obtained -from :term:`ACL` objects attached to model instances. +from :term:`ACL` objects attached to :term:`resource` objects. Attributes ~~~~~~~~~~ diff --git a/docs/zcml/asset.rst b/docs/zcml/asset.rst new file mode 100644 index 000000000..af7a6db94 --- /dev/null +++ b/docs/zcml/asset.rst @@ -0,0 +1,65 @@ +.. _asset_directive: + +``asset`` +--------- + +The ``asset`` directive adds an asset override for a single +static file/directory asset. + +Attributes +~~~~~~~~~~ + +``to_override`` + A :term:`asset specification` specifying the asset to be + overridden. + +``override_with`` + A :term:`asset specification` specifying the asset which + is used as the override. + +Examples +~~~~~~~~ + +.. topic:: Overriding a Single Asset File + + .. code-block:: xml + :linenos: + + + +.. topic:: Overriding all Assets in a Package + + .. code-block:: xml + :linenos: + + + +.. topic:: Overriding all Assets in a Subdirectory of a Package + + .. code-block:: xml + :linenos: + + + +Alternatives +~~~~~~~~~~~~ + +The :meth:`pyramid.config.Configurator.override_asset` +method can be used instead of the ``resource`` ZCML directive. + +This directive can also be invoked as the ``resource`` ZCML directive for +backwards compatibility purposes. + +See Also +~~~~~~~~ + +See also :ref:`asset_zcml_directive`. diff --git a/docs/zcml/handler.rst b/docs/zcml/handler.rst index 301bf7895..01d442ab6 100644 --- a/docs/zcml/handler.rst +++ b/docs/zcml/handler.rst @@ -28,7 +28,7 @@ Attributes ``factory`` The :term:`dotted Python name` to a function that will generate a :app:`Pyramid` context object when the associated route matches. - e.g. ``mypackage.models.MyFactoryClass``. If this argument is not + e.g. ``mypackage.resources.MyResource``. If this argument is not specified, a default root factory will be used. ``xhr`` diff --git a/docs/zcml/resource.rst b/docs/zcml/resource.rst deleted file mode 100644 index 3f7c58faa..000000000 --- a/docs/zcml/resource.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _resource_directive: - -``resource`` ------------- - -The ``resource`` directive adds a resource override for a single -resource. - -Attributes -~~~~~~~~~~ - -``to_override`` - A :term:`resource specification` specifying the resource to be - overridden. - -``override_with`` - A :term:`resource specification` specifying the resource which - is used as the override. - -Examples -~~~~~~~~ - -.. topic:: Overriding a Single Resource File - - .. code-block:: xml - :linenos: - - - -.. topic:: Overriding all Resources in a Package - - .. code-block:: xml - :linenos: - - - -.. topic:: Overriding all Resources in a Subdirectory of a Package - - .. code-block:: xml - :linenos: - - - -Alternatives -~~~~~~~~~~~~ - -The :meth:`pyramid.config.Configurator.override_resource` -method can be used instead of the ``resource`` ZCML directive. - -See Also -~~~~~~~~ - -See also :ref:`resource_zcml_directive`. diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst index 4f7cdb955..ac9261e27 100644 --- a/docs/zcml/route.rst +++ b/docs/zcml/route.rst @@ -25,7 +25,7 @@ Attributes ``factory`` The :term:`dotted Python name` to a function that will generate a :app:`Pyramid` context object when this route matches. - e.g. ``mypackage.models.MyFactoryClass``. If this argument is not + e.g. ``mypackage.resources.MyResource``. If this argument is not specified, a default root factory will be used. ``view`` diff --git a/docs/zcml/view.rst b/docs/zcml/view.rst index 74d497cb3..6887f88fb 100644 --- a/docs/zcml/view.rst +++ b/docs/zcml/view.rst @@ -157,7 +157,7 @@ Predicate Attributes representing the class that a graph traversal parent object of the :term:`context` must be an instance of (or :term:`interface` that a parent object must provide) in order for this view to be found and - called. Your models must be "location-aware" to use this feature. + called. Your resources must be "location-aware" to use this feature. See :ref:`location_aware` for more information about location-awareness. @@ -222,7 +222,7 @@ Examples :linenos: @@ -232,7 +232,7 @@ Examples :linenos: diff --git a/pyramid/config.py b/pyramid/config.py index 2e64d49e9..c82e15ae6 100644 --- a/pyramid/config.py +++ b/pyramid/config.py @@ -73,8 +73,8 @@ from pyramid.path import package_of from pyramid.registry import Registry from pyramid.renderers import RendererHelper from pyramid.request import route_request_iface -from pyramid.resource import PackageOverrides -from pyramid.resource import resolve_resource_spec +from pyramid.asset import PackageOverrides +from pyramid.asset import resolve_asset_spec from pyramid.settings import Settings from pyramid.static import StaticURLInfo from pyramid.threadlocal import get_current_registry @@ -327,14 +327,14 @@ class Configurator(object): self.action(IAuthorizationPolicy, None) def _make_spec(self, path_or_spec): - package, filename = resolve_resource_spec(path_or_spec, - self.package_name) + package, filename = resolve_asset_spec(path_or_spec, + self.package_name) if package is None: return filename # absolute filename return '%s:%s' % (package, filename) def _split_spec(self, path_or_spec): - return resolve_resource_spec(path_or_spec, self.package_name) + return resolve_asset_spec(path_or_spec, self.package_name) def _derive_view(self, view, permission=None, predicates=(), attr=None, renderer=None, wrapper_viewname=None, @@ -570,19 +570,21 @@ class Configurator(object): this Configurator's constructor.""" return self.name_resolver.maybe_resolve(dotted) - def absolute_resource_spec(self, relative_spec): - """ Resolve the potentially relative :term:`resource + def absolute_asset_spec(self, relative_spec): + """ Resolve the potentially relative :term:`asset specification` string passed as ``relative_spec`` into an - absolute resource specification string and return the string. + absolute asset specification string and return the string. Use the ``package`` of this configurator as the package to - which the resource specification will be considered relative - when generating an absolute resource specification. If the + which the asset specification will be considered relative + when generating an absolute asset specification. If the provided ``relative_spec`` argument is already absolute, or if the ``relative_spec`` is not a string, it is simply returned.""" if not isinstance(relative_spec, basestring): return relative_spec return self._make_spec(relative_spec) + absolute_resource_spec = absolute_asset_spec # b/w compat forever + def setup_registry(self, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, @@ -2283,18 +2285,18 @@ class Configurator(object): self.registry.registerUtility(policy, IAuthorizationPolicy) self.registry.registerUtility(policy, IAuthenticationPolicy) - def testing_models(self, models): + def testing_resources(self, resources): """Unit/integration testing helper: registers a dictionary of - :term:`model` objects that can be resolved via the - :func:`pyramid.traversal.find_model` API. + :term:`resource` objects that can be resolved via the + :func:`pyramid.traversal.find_resource` API. - The :func:`pyramid.traversal.find_model` API is called with + The :func:`pyramid.traversal.find_resource` API is called with a path as one of its arguments. If the dictionary you register when calling this method contains that path as a string key (e.g. ``/foo/bar`` or ``foo/bar``), the - corresponding value will be returned to ``find_model`` (and + corresponding value will be returned to ``find_resource`` (and thus to your code) when - :func:`pyramid.traversal.find_model` is called with an + :func:`pyramid.traversal.find_resource` is called with an equivalent path string or tuple. """ class DummyTraverserFactory: @@ -2303,14 +2305,16 @@ class Configurator(object): def __call__(self, request): path = request['PATH_INFO'] - ob = models[path] + ob = resources[path] traversed = traversal_path(path) return {'context':ob, 'view_name':'','subpath':(), 'traversed':traversed, 'virtual_root':ob, 'virtual_root_path':(), 'root':ob} self.registry.registerAdapter(DummyTraverserFactory, (Interface,), ITraverser) - return models + return resources + + testing_models = testing_resources # b/w compat @action_method def testing_add_subscriber(self, event_iface=None): diff --git a/pyramid/includes/meta.zcml b/pyramid/includes/meta.zcml index 864cff564..9f3726cc9 100644 --- a/pyramid/includes/meta.zcml +++ b/pyramid/includes/meta.zcml @@ -49,7 +49,7 @@