diff options
Diffstat (limited to 'docs/narr/static.rst')
| -rw-r--r-- | docs/narr/static.rst | 76 |
1 files changed, 50 insertions, 26 deletions
diff --git a/docs/narr/static.rst b/docs/narr/static.rst index 9547e73fc..172fb08d4 100644 --- a/docs/narr/static.rst +++ b/docs/narr/static.rst @@ -1,8 +1,8 @@ Static Resources ================ -:app:`Pyramid` makes it possible to serve up "static" (non-dynamic) -resources from a directory on a filesystem. This chapter describes +:app:`Pyramid` makes it possible to serve up static +resources files from a directory on a filesystem. This chapter describes how to configure :app:`Pyramid` to do so. .. index:: @@ -20,7 +20,7 @@ application root URL, e.g. ``/static``. Note that the ``path`` provided to :meth:`pyramid.config.Configurator.add_static_view` may be a fully -qualified :term:`resource specification` or an *absolute path*. +qualified :term:`resource specification`, or an *absolute path*. Here's an example of a use of :meth:`pyramid.config.Configurator.add_static_view` that will serve @@ -100,7 +100,7 @@ provided with a ``name`` argument that is the URL prefix ``http://example.com/images``, subsequent calls to :func:`pyramid.url.static_url` with paths that start with the ``path`` argument passed to :meth:`pyramid.config.Configurator.add_static_view` -will generate a URL something like ``http://example.com/logo.png``. The +will generate a URL something like ``http://example.com/images/logo.png``. The external webserver listening on ``example.com`` must be itself configured to respond properly to such a request. The :func:`pyramid.url.static_url` API is discussed in more detail later in this chapter. @@ -110,6 +110,25 @@ to :meth:`pyramid.config.Configurator.add_static_view`. Use of the :ref:`static_directive` ZCML directive is completely equivalent to using imperative configuration for the same purpose. +.. note:: + + Using :func:`pyramid.url.static_url` in conjunction with a + :meth:`pyramid.configuration.Configurator.add_static_view` makes it + possible to put static media on a separate webserver during production (if + the ``name`` argument to + :meth:`pyramid.configuration.Configurator.add_static_view` is a URL), + while keeping static media package-internal and served by the development + webserver during development (if the ``name`` argument to + :meth:`pyramid.configuration.Configurator.add_static_view` is a view + name). To create such a circumstance, we suggest using the + :attr:`pyramid.registry.Registry.settings` API in conjunction with a + setting in the application ``.ini`` file named ``media_location``. Then + set the value of ``media_location`` to either a view name or a URL + depending on whether the application is being run in development or in + production (use a different `.ini`` file for production than you do for + development). This is just a suggestion for a pattern; any setting name + other than ``media_location`` could be used. + .. index:: single: generating static resource urls single: static resource urls @@ -133,8 +152,8 @@ For example, let's assume you create a set of static declarations like so: config.add_static_view(name='static1', path='mypackage:resources/1') config.add_static_view(name='static2', path='mypackage:resources/2') -These declarations create URL-accessible directories which have URLs which -begin, respectively, with ``/static1`` and ``/static2``. The resources in +These declarations create URL-accessible directories which have URLs that +begin with ``/static1`` and ``/static2``, respectively. The resources in the ``resources/1`` directory of the ``mypackage`` package are consulted when a user visits a URL which begins with ``/static1``, and the resources in the ``resources/2`` directory of the ``mypackage`` package are consulted when a @@ -178,7 +197,7 @@ instead of a view name. For example, the ``name`` argument may be .. code-block:: python :linenos: - config.add_static_view(name='static1', path='mypackage:images') + config.add_static_view(name='http://example.com/images', path='mypackage:images') Under such a configuration, the URL generated by ``static_url`` for resources which begin with ``mypackage:images`` will be prefixed with @@ -206,7 +225,7 @@ The :class:`pyramid.view.static` helper class is used to perform this task. This class creates an object that is capable acting as a :app:`Pyramid` view callable which serves static resources from a directory. For instance, to serve files within a directory located on -your filesystem at ``/path/to/static/dir`` mounted at the URL path +your filesystem at ``/path/to/static/dir`` from the URL path ``/static`` in your application, create an instance of the :class:`pyramid.view.static` class inside a ``static.py`` file in your application root as below. @@ -219,13 +238,10 @@ your application root as below. static_view = static('/path/to/static/dir') .. note:: the argument to :class:`pyramid.view.static` can also be - a relative pathname, e.g. ``my/static`` (meaning relative to the + a "here-relative" pathname, e.g. ``my/static`` (meaning relative to the Python package of the module in which the view is being defined). It can also be a :term:`resource specification` - (e.g. ``anotherpackage:some/subdirectory``) or it can be a - "here-relative" path (e.g. ``some/subdirectory``). If the path is - "here-relative", it is relative to the package of the module in - which the static view is defined. + (e.g. ``anotherpackage:some/subdirectory``). Subsequently, you may wire this view up to be accessible as ``/static`` using the :mod:`pyramid.config.Configurator.add_view` method in your @@ -238,25 +254,33 @@ represents your root object. config.add_view('mypackage.static.static_view', name='static', context='mypackage.models.Root') -In this case, ``mypackage.models.Root`` refers to the class of which your -:app:`Pyramid` application's root object is an instance. +In this case, ``mypackage.models.Root`` refers to the class of your +:app:`Pyramid` application's traversal root object. -You can also omit the ``context`` argument if you want the name ``static`` to -be accessible as the static view against any model. This will also allow -``/static/foo.js`` to work, but it will allow for ``/anything/static/foo.js`` -too, as long as ``anything`` itself is resolvable. +The context argument above limits where the static view is accessible to +URL paths directly under the root object. If you omit the ``context`` +argument, then ``static`` will be accessible as the static view against +any model object in the traversal graph. This will allow +``/static/foo.js`` to work, but it will also allow for +``/anything/static/foo.js`` too, as long as ``anything`` can be +resolved. Note that you cannot use the :func:`pyramid.url.static_url` API to generate URLs against resources made accessible by registering a custom static view. .. warning:: - To ensure that model objects contained in the root don't "shadow" - your static view (model objects take precedence during traversal), - or to ensure that your root object's ``__getitem__`` is never - called when a static resource is requested, you can refer to your - static resources as registered above in URLs as, - e.g. ``/@@static/foo.js``. This is completely equivalent to - ``/static/foo.js``. See :ref:`traversal_chapter` for information + When adding a static view to your root object, you need to be + careful that there are no model objects contained in the + root with the same key as the view name (e.g., ``static``). + Model objects take precedence during traversal, + thus such a name collision will cause the model to "shadow" + your static view. To avoid this issue, and ensure that your + root object's ``__getitem__`` is never + called when a static resource is requested, you can refer to them + unambiguously using the ``@@`` prefix (goggles) in their URLs. + For the above examples you could use '/@@static/foo.js' + instead of '/static/foo.js' to avoid such shadowing. + See :ref:`traversal_chapter` for information about "goggles" (``@@``). |