Make miscellaneous improvements to the API developer experience

[dhruvkb]

Description

This PR

• disables caching of templates during development (otherwise template changes do not reflect unless the server is reloaded)
• fixes the verbose name of the API (so that "Api" is no longer used)
• fixes the verbose name of model fields with the acronym URL (so that "url" or "Url" are no longer used)

While the addition of the verbose names does lead to a new migration, the migration is a no-op in SQL.

SQL

BEGIN;
--
-- Alter field creator_url on audio
--
-- (no-op)
--
-- Alter field foreign_landing_url on audio
--
-- (no-op)
--
-- Alter field url on audio
--
-- (no-op)
--
-- Alter field creator_url on audioset
--
-- (no-op)
--
-- Alter field foreign_landing_url on audioset
--
-- (no-op)
--
-- Alter field url on audioset
--
-- (no-op)
--
-- Alter field creator_url on image
--
-- (no-op)
--
-- Alter field foreign_landing_url on image
--
-- (no-op)
--
-- Alter field url on image
--
-- (no-op)
COMMIT;

Checklist

• My pull request has a descriptive title (not a vague title likeUpdate index.md).
• My pull request targets the default branch of the repository (main) or a parent feature branch.
• My commit messages follow best practices.
• My code follows the established code style of the repository.
• I added or updated tests for the changes I made (if applicable).
• I added or updated documentation (if applicable).
• I tried running the project locally and verified that there are no visible errors.
• I ran the DAG documentation generator (just catalog/generate-docs for catalog
  PRs) or the media properties generator (just catalog/generate-docs media-props
  for the catalog or just api/generate-docs for the API) where applicable.

Developer Certificate of Origin

Developer Certificate of Origin

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

[sarayourfriend]

Our usage of uvicorn reload instead of Django's development mode causes some of Django's normal dev-mode features not to work by default, I guess this is one of them. Did you happen to try configuring uvicorn's reload watcher pattern instead of changing Django's template caching behaviour?

https://www.uvicorn.org/settings/#reloading-with-watchfiles

It'd be nice to actually keep template caching locally when the templates aren't changing, so that at least we would theoretically see an issue if template caching caused an issue when it ran. If we tell uvicorn to also reload when templates change, then the Django configuration wouldn't need to change between prod and local. This seems to work for me locally:

diff --git a/api/run.py b/api/run.py
index 0265ad680..521625007 100644
--- a/api/run.py
+++ b/api/run.py
@@ -18,6 +18,8 @@ if __name__ == "__main__":
             ".",  # default, API directory
             "../packages/python/",
         ],
+        # *.py is default, add *.html so template changes also cause reloads
+        reload_includes=["*.py", "*.html"],
         log_level="debug",
         access_log=False,
     )

That should let us avoid needing to mess with the template loader configuration at all.

Can you confirm whether you've tried this, and if it doesn't work can you document in the PR why? This LGTM to me otherwise, and happy to approve it, but wanted to make sure there wasn't a potentially simpler solution that would also avoid introducing a meaningful difference in the way templates are processed locally vs in production.

[dhruvkb]

This PR is exactly what Django used to do before version 4.1. In subsequent versions, they enabled caching of templates locally, and this PR just reverses their change.

We could configure Uvicorn to track HTML files and reload if they've changed but I didn't even try that because this worked.

I'll try out the Uvicorn change you have suggested.

[sarayourfriend]

This PR is exactly what Django used to do before version 4.1. In subsequent versions, they enabled caching of templates locally, and this PR just reverses their change.

Good to know! In that case, the difference between local and production I suppose we don't need to worry about (though they changed it for some reason, I guess?). If the uvicorn settings approach is simpler, then great, otherwise this works too 👍

[github-actions]

This PR has migrations. Please rebase it before merging to ensure that conflicting migrations are not introduced.

[dhruvkb]

The change to reload Uvicorn when templates works well and is much more minimal compared to changing the loaders, so I've updated the PR.

One thing to note is that disabling caching by changing the loaders (the previous implementation of this PR) was slightly faster during development as it did not require a full reload of Uvicorn. It would continue the Python process and merely read the latest contents of the template file from disk each time.

[obulat]

Nice improvements, thank you for finding them!

[sarayourfriend]

LGTM!