Merge pull request #10 from Brown-University-Library/update-install-i…

…nstructions

updates packages and instructions.

README.md

@@ -1,20 +1,29 @@
 # purpose
 
-This is a template for new django projects -- to standardize on some nice features/practices, and to get up and running, locally, easily and quickly. It provides instructions for getting the code from GitHub, installing it, setting up a virtual environment, and lists a few things to try after getting the webapp running. Finally, it lists the nice features/practices.
+This is a template for new django projects -- to standardize on some nice features/practices, and to get up and running, locally, easily and quickly. It provides instructions for getting the template from GitHub, customizing it, starting the webapp, and lists a few things to try with the webapp running. Finally, it lists the nice features/practices, and also shows typical usage.
+
+on this page...
+- [local quick-start](#local-quick-start)
+- [stuff to try](#stuff-to-try)
+- [nice features/practices](#nice-featurespractices)
+- [regular setup](#regular-setup)
 
 --- 
 
 
-# local-install
+# local quick-start
 
-Notes about the install instructions...
+Notes about the quick-start instructions...
 
-- The install-instructions below assume:
+- The instructions below assume:
     - a unix-like environment (ie Mac, Linux, or Windows Subsystem for Linux (WSL)). 
     - you've installed `uv` ([link][uv_link])
-        - For now, here's a link to an [older version][old] of the repo that uses `pip`-based setup instructions. When improvements are made to this repo, this link will be removed.
-- The install-instructions below reference `x_project_stuff`, `x_project`, and `x_app`. In all cases replace with the name of your project, like: `isbn_api_project_stuff`, `isbn_api_project`, and `isbn_api_app`.
+        - _For now, here's a link to an [older version][old] of the repo that uses `pip`-based setup instructions. When improvements are made to this repo, this link will be removed._
+
+- The instructions below reference `x_project_stuff`, `x_project`, and `x_app`. In all cases replace with the name of your project, like: `isbn_api_project_stuff`, `isbn_api_project`, and `isbn_api_app`.
+
 - The `update_project_and_app_references.py` script ([link](https://github.com/Brown-University-Library/django_template_42_project/blob/main/update_project_and_app_references.py)) deletes the cloned `.git` directory (in addition to its main purpose to rename the project). Why? So you don't accidentally start building away and commit to the template repo. After this installation, creating a new git repo is one of the first things you should do.
+
 - When you start the webapp via `runserver`, you'll get a message that there are migrations that need to be run, with instructions. You can go ahead and do that, or do it later.
 
 ```bash
@@ -45,6 +54,7 @@ That's it!
 
 ---
 
+
 # stuff to try
 
 - Open a browser to <http://127.0.0.1:8000/>. That'll redirect to <http://127.0.0.1:8000/info/>. 
@@ -58,7 +68,7 @@ That's it!
 
     You won't initially see anything, but if you reload the error-check url, and then check this terminal window again, you'll see the email-data that would have been sent.
 
-- Try <http://127.0.0.1:8000/version/>. Once you `git init`, `git add --all`, and `git commit -am "initial commit"`, it'll show the branch and commit -- super-handy for dev and prod confirmations.
+- Try <http://127.0.0.1:8000/version/>. Once you `git init`, `git add --all`, and `git commit -am "initial commit"`, it'll show the branch and commit -- _very_ handy for dev and prod confirmations.
 
 - Try `$ uv run ./manage.py test`. There are two simple tests that should pass.
 
@@ -79,10 +89,36 @@ Next -- well, the sky's the limit!
 - Includes a couple of client-get tests that respond differentially to dev and prod settings.
 - Includes a dev-only error-check url (enables confirmation that email-admins-on-error is set up correctly).
 - Uses python-dotenv.
-- Uses tilde-comparators in the `.in` requirements files for stable upgrades.
-- Uses layered `base.in` and `server.in` requirements files which will produce `.txt` files -- for clarity re what's really in the venv. 
 - Specifies compatible package versions for reliable staging and prod deployment.
+    - Uses tilde-comparators in the `.in` requirements files for stable upgrades.
+    - Uses layered `base.in` and `server.in` requirements files which will produce `.txt` files -- for clarity re what's really in the venv. 
 - Shows one possible pattern to make async calls (`app/lib/version_helper.manage_git_calls()`) and gather together the results.
 - This webapp doesn't access the db much, but if it did, and you wanted to inspect the sql generated by the ORM, uncomment out the `django.db.backends` logger in `settings.py`.
+- Includes a default config-file for `ruff`, a fast, extensible python linter that can integrate with many popular code editors such as VS Code, PyCharm, and others.
+
+---
+
+
+# regular setup
+
+The `local quick-start` instructions above are to get you up-and-running super quickly and easily. Below are instructions for a more typical local virtual-environment architecture (they assume you've already followed the `local quick-start` instructions).
+
+Make the venv...
+
+```bash
+$ cd ./x_project_stuff/
+$ uv venv ./your_venv --python 3.8.10
+$ cd ./x_project
+$ source ../your_venv/bin/activate
+(your_venv) $ uv pip sync ./config/requirements/requirements_base.txt
+```
+
+That's a one-time setup. For regular use...
+
+```bash
+$ cd ./x_project_stuff/x_project
+$ source ../your_venv/bin/activate
+(your_venv) $ python ./manage.py runserver
+```
 
 ---

config/requirements/requirements_base.in

@@ -1,6 +1,5 @@
 Django~=4.2.0
-pip-tools~=7.4.0
 python-dotenv~=1.0.0
-requests~=2.27.0    # for down-stream compatibility
+requests~=2.32.3
 trio~=0.26.0
 urllib3~=1.26.0     # for down-stream compatibility

config/requirements/requirements_base.txt

@@ -0,0 +1,48 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile ./config/requirements/requirements_base.in --output-file ./config/requirements/requirements_base.txt --universal --python 3.8
+asgiref==3.8.1
+    # via django
+attrs==24.2.0
+    # via
+    #   outcome
+    #   trio
+backports-zoneinfo==0.2.1 ; python_full_version < '3.9'
+    # via django
+certifi==2024.8.30
+    # via requests
+cffi==1.17.1 ; implementation_name != 'pypy' and os_name == 'nt'
+    # via trio
+charset-normalizer==3.4.0
+    # via requests
+django==4.2.16
+    # via -r ./config/requirements/requirements_base.in
+exceptiongroup==1.2.2 ; python_full_version < '3.11'
+    # via trio
+idna==3.10
+    # via
+    #   requests
+    #   trio
+outcome==1.3.0.post0
+    # via trio
+pycparser==2.22 ; implementation_name != 'pypy' and os_name == 'nt'
+    # via cffi
+python-dotenv==1.0.1
+    # via -r ./config/requirements/requirements_base.in
+requests==2.32.3
+    # via -r ./config/requirements/requirements_base.in
+sniffio==1.3.1
+    # via trio
+sortedcontainers==2.4.0
+    # via trio
+sqlparse==0.5.2
+    # via django
+trio==0.26.2
+    # via -r ./config/requirements/requirements_base.in
+typing-extensions==4.12.2 ; python_full_version < '3.11'
+    # via asgiref
+tzdata==2024.2 ; sys_platform == 'win32'
+    # via django
+urllib3==1.26.20
+    # via
+    #   -r ./config/requirements/requirements_base.in
+    #   requests

ruff.toml

@@ -1,5 +1,5 @@
 ## settings ##
-line-length = 100
+line-length = 125
 indent-width = 4
 target-version = "py38"
 
@@ -16,4 +16,7 @@ avoid-escape = true
 case-sensitive = true
 
 [lint.pycodestyle]
-max-line-length = 100
+max-line-length = 125
+
+[lint.pydocstyle]
+convention = "google"