How does Pyramid's add_static_view work?

Question

How does add_static_view(name, path) in Pyramid work?

From the docstring:

"The name argument is a string representing an application-relative local URL prefix. It may alternately be a full URL. The path argument is the path on disk where the static files reside. This can be an absolute path, a package-relative path, or an asset specification."

Somehow I have got the impression that this description is not very accurate.

If I add some code along the lines of

config.add_static_view("static", "/path/to/resource/on/filesystem")

and I visit

http://localhost:PORT/static/logo.png  

I see the logo.png given that it can be found in

/path/to/resource/on/filesystem/

Now, if I have some code like the following

config.add_static_view("http://myfilehoster.com/images", "myproject:images")

the description that "the path argument is the path on disk where the static files reside" does not seem accurate anymore because the actual files reside on the disk of myfilehoster. It seems to me that I am merely registering some kind of identifier (myproject:images) that I can use within my program code to reference the "real" location "http://myfilehoster.com/images". E.g.

request.static_url("myproject:images/logo.png") 

would be resolved to "http://myfilehoster.com/images/logo.png".

So is the documentation inaccurate here or am I missing something?

Answer 1

You are missing something. In the narrative documentation on static assets it states:

Instead of representing a URL prefix, the name argument of a call to add_static_view() can alternately be a URL. Each of examples we’ve seen so far have shown usage of the name argument as a URL prefix. However, when name is a URL, 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 pyramid.request.Request.static_url().

In the API documentation similar wording is used:

When add_static_view is called with a name argument that represents a URL prefix, as it is above, subsequent calls to pyramid.request.Request.static_url() with paths that start with the path argument passed to add_static_view will generate a URL something like http://<Pyramid app URL>/images/logo.png, which will cause the logo.png file in the images subdirectory of the mypackage package to be served.

Using a URL switches the behaviour of add_static_view altogether and the path argument is interpreted as a symbolic path only for the .static_url() method. That latter detail is perhaps not described as explicitly in the documentation, you could file an issue in the pyramid issue tracker if you feel strongly about that.