What does upload in Google AppEngine app.yaml do?

Question

I am going through the various Google AppEngine tutorials sometimes, and I just noticed something odd in a StackOverflow question about favicon.ico - specifically this question: favicon.ico "not found error" in app engine

- url: /favicon.ico
static_files: media/img/favicon.ico
upload: media/img/favicon.ico

- url: /robots.txt
static_files: media/robots.txt
upload: media/robots.txt

All of the posters included an "upload:" line in their app.yaml definitions The application appears to work the same with or without the upload: line, and I have not seen any mention of it in the official documentation.

Where is it used, or what difference does it make if this line is included or not?

Answer 1

I have been reading the docs over and over again in the hopes of understanding this better. This is what I have inferred from it.

App Engine says that it uploads our static files and application code to separate locations. In order to do this, it must know which files are static - this is specified through the upload parameter.

However, this raises some questions regarding the design of the parameters specified in app.yaml.

1. Could App Engine have inferred which files are static from the static_files parameter alone?

   In your example, the value of the static_files parameter was identical to the value of the upload parameter (i.e. media/img/favicon.ico). However, in general, the value of the static_files parameter differs from the value of the upload parameter. The static_files parameter is there to allow matching groups from the url pattern to be substituted into it, in order to generate file path, e.g.
   - url: /item-(.*?)/category-(.*) static_files: archives/\2/items/\1 upload: archives/(.*?)/items/(.*)

2. Could App Engine have inferred which files are static from the url parameter alone?

   In general, no, because the resource hierarchy implied by the url may not be identical to the actual folder structure. For example, I might have put my index.html into a subfolder, but I might want to access it with the root url "hello.appspot.com/", rather than "hello.appspot.com/subfolder/".

3. Could App Engine have inferred which files are static using both the url parameter and the static_files parameter?

   It seems feasible to write a function that returns an upload pattern given both the url parameter and static_files parameter, thereby negating the need for an explicit upload parameter. I would think it works for simple cases, however, there is probably a reason unbeknownst to me that the docs write "the handler cannot determine which files in your application directory correspond with the given url and static_files patterns".

url: The URL pattern, as a regular expression. The expression can contain groupings that can be referred to in the file path to the script with regular expression back-references. For example, /item-(.?)/category-(.) would match the URL /item-127/category-fruit, and use 127 and fruit as the first and second groupings.
handlers:
- url: /item-(.*?)/category-(.*) static_files: archives/\2/items/\1

static_files: The path to the static files matched by the URL pattern, from the application root directory. The path can refer to text matched in groupings in the URL pattern. As in the previous example, archives/\2/items/\1 inserts the second and first groupings matched in place of \2 and \1, respectively. With the pattern in the example above, the file path would be archives/fruit/items/127.

upload: A regular expression that matches the file paths for all files that will be referenced by this handler. This is necessary because the handler cannot determine which files in your application directory correspond with the given url and static_files patterns. Static files are uploaded and handled separately from application files. The example above might use the following upload pattern: archives/(.*?)/items/(.*)

---

On an additional note, the alternative to using static_files is to use static_dir if the entire directory can be marked as static. In this case, the upload parameter is not needed, since static_dir should point to an actual directory and thus App Engine will simply upload the entire directory to where it stores the static files. However, note that the use of the url parameter will be different in this case.

url: A URL prefix. This value uses regular expression syntax (and so regexp special characters must be escaped), but it should not contain groupings. All URLs that begin with this prefix are handled by this handler, using the portion of the URL after the prefix as part of the file path.

static_dir: The path to the directory containing the static files, from the application root directory. Everything after the end of the matched url pattern is appended to static_dir to form the full path to the requested file. All files in this directory are uploaded with the application as static files.