expo/expoweb
1
0
Fork 0
mirror of https://expo.survex.com/repositories/expoweb/.git/ synced 2024-12-18 14:32:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

uv not pip - online edit of handbook/troggle/trogdjangup.html [PosixPath('/home/philip/expo/expoweb/handbook/troggle/trogdjangup.html')]

Browse Source
This commit is contained in:
Philip Sargent 2024-12-15 23:00:41 +00:00
parent 5f2d044c97
commit 3685f03461
1 changed files with 30 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
handbook/troggle/trogdjangup.html
View File

@ -10,9 +10,10 @@
<h2 id="tophead">CUCC Expedition Handbook</h2>
<h1>Upgrading Django for Troggle</h1>
<h4>Why this used to be difficult</h4>
<p>Before Django 3.0, when Django was upgraded to a new version things broke across the entire django package, including things which we don't conciously use but are internal dependencies within Django. These were 'the way to do it' when troggle was first written for Django 0.7 in 2006. So upgrading troggle to a new Django version required not just a broad beadth of knowledge across troggle, but also across the entire breadth of django itself. And the error messages are sometimes very unhelpful. This is <em>no longer the case</em> and the Django organisation has a very clear "non-breaking" policy between LTS releases.
<p>Before Django 3.0, whenever Django was upgraded to a new version things broke across the entire django package, including things which we don't conciously use but are internal dependencies within Django. These were 'the way to do it' when troggle was first written for Django 0.7 in 2006. So upgrading troggle to a new Django version required not just a broad beadth of knowledge across troggle, but also across the entire breadth of django itself. And the error messages are sometimes very unhelpful. This is <em>no longer the case</em> and the Django organisation has a very clear "non-breaking" policy between LTS releases.
<p>Now read <a href="trogdjango.html">Django and Troggle</a> if you haven't already.
<p>Note that Django 3.2 is out of support since April 2024.
<h4>Django versions and update schedule</h4>
<div align="center">
@ -132,16 +133,16 @@ troggle test suite. See <a href="troglaptop.html">how to set up a troggle softwa
sqlite database browser software very helpful and that you will need to know git.
<h3 id="djangotricks">Important Tricks</h3>
[I. November 2024 we are planning on moving from pip to uv for managing python vitrual environments.]
<p>There are six critical tricks that make everything much, much easier:
<ol>
<li>Use <a href="https://docs.python.org/3/library/venv.html">pip venv</a> or virtualenv to set up a virtual python environment within which you can easily and quickly change the specific releases of python, django, django's dependencies and django plugins.
With a previously created venv <var>py39d32</var> start it up like this:<br />
<var>cd py39d32<br />
source bin/activate<br />
<li>Use a virtual python environment within which you can easily and quickly change the specific releases of python, django, django's dependencies and django plugins.
With a previously created envornment <var>.venv</var> start it up like this:<br />
cd ~/expo/troggle<br />
source .venv/bin/activate<br />
python --version<br />
cd troggle<br />
django-admin<br />
python manage.py<br />
python manage.py check -v 3<br />
@ -190,10 +191,25 @@ release note. <a href="https://docs.djangoproject.com/en/4.2/releases/4.2/">From
<h4>Running troggle before and after a Django migration</h4>
<ol>
<li>ensure that you have the exact version of python installed on your machine as is live for troggle on the server, e.g. do <var>$ sudo apt install python3.7.5</var>.
<li>create a venv using the version of python to be used. <br>We have a script to help you do this in <var>:troggle:venv-trog.sh</var> (but it is fragile and often broken)
<li>do <a href="troglaptop.html">a clean install</a> of django and troggle.
<li>check the versions of plugins using <var>pip list -o</a>
<li>ensure that you have the exact same version of python installed on your machine as is live for troggle on the server, so check the line <br />
<code>requires-python = "&gt;=3.11,&lt;3.12"</code><br />
in the file <var>server.toml</var>.
<li>Copy <var>server.toml</var> on top of <var>pyprojectr.toml</var> and synchronise the environment: <var>uv sync</var>.
<li>check the versions of plugins using <var>uv tree</var>
<pre><code>(troggle) philip@Mohawk:~/expo/troggle$ uv tree --all-groups
Resolved 11 packages in 0.54ms
troggle-server v2024.12.1
├── beautifulsoup4 v4.11.2 (group: server)
│ └── soupsieve v2.6
├── coverage v7.6.9 (group: server)
├── django v3.2.19 (group: server)
│ ├── asgiref v3.8.1
│ ├── pytz v2024.2
│ └── sqlparse v0.5.3
├── piexif v1.1.3 (group: server)
├── pillow v9.4.0 (group: server)
└── unidecode v1.3.6 (group: server)</code></pre>
<li>open two terminal windows:
<ul>
<li>- one will be used for installations and tests.
@ -206,7 +222,7 @@ release note. <a href="https://docs.djangoproject.com/en/4.2/releases/4.2/">From
<li>testing:
<ul>
<li>run <var>troggle$ python manage.py test</var>
<li>run the full data import <var>troggle$ python databaseReset.py reset R000</var>. It should take about 5 minutes to import everything (11 minutes on a slow core 2 duo laptop). ("R000" is just a label, use whatever you like.)
<li>run the full data import <var>troggle$ python databaseReset.py reset R000</var>. It should take between 40s and 1 minute or so to import everything (11 minutes on an old slow core 2 duo laptop). ("R000" is just a label, use whatever you like.)
<li>start the runserver in the other terminal window and open a web browser to http://localhost:8000 and check important pages which we don't have tests for (yet). These are listed in <a href="troglaptop.html">the troggle laptop installation instuctions</a>.
</ul>
@ -214,40 +230,11 @@ release note. <a href="https://docs.djangoproject.com/en/4.2/releases/4.2/">From
<li>run the script <var>./pre-run.sh</var> to clean up everything before the next round of tests.
</ol>
<h3>Django dependencies</h3>
<p>You can upgrade the version of python installed within pip venv but not downgrade. So get that first venv installed right.
<p>Here is example of installed (Version) and most-recent-available (Latest) verisons of pip installations.
<pre><code>Package Version Latest Type
---------- ------- ------ -----
Django 2.2.19 3.2 wheel
docutils 0.14 0.17 wheel</code></pre>
<p>This only gives any output for packages which are not the most recent. To see what is actually installed use
<pre><code>$ pip freeze
confusable-homoglyphs==3.2.0
Django==2.2.19
docutils==0.17
Pillow==8.2.0
pytz==2021.1
sqlparse==0.4.1
Unidecode==1.2.0</code></pre>
Although the above all work fine, on debian <var>buster</var> we were actually using the standard installs on that version of debian which are older:
<pre><code>$ pip freeze
confusable-homoglyphs==3.2.0
Django==2.2.19
docutils==0.14
Pillow==5.4.1
pytz==2019.1
sqlparse==0.2.4
Unidecode==1.0.23</code></pre>
<p>To upgrade pip istelf, do <var>$ pip install --upgrade pip</var>
<h3>Django database dependencies</h3>
<p>On the expo server we run MariaDB as the database which has its own dependencies. In particular under debian buster we
had to use MariaDB v1.3.10 which was the latest version supported by buster:
had to use MariaDB v1.3.10 which was the latest version supported by Debian buster:
<pre><code>mysqlclient==1.3.10
</code></pre>which is technically incompatible with Django 2.2 which requires 1.3.13.
@ -255,7 +242,7 @@ This incompatibility is a policy choice by the Django team. Wookey ran the Djang
Django just didn't support it because they couldn't spare the effort to test it.
<h4>To run Django's system test suite:</h4>
<p>This is only necessary if we hit a policy-imposed incomatibility, as we did with mysqlclient==1.3.10 . We have only ever had to do this once.
<p>This is only necessary if we hit a policy-imposed incompatibility, as we did with mysqlclient==1.3.10 . We have only ever had to do this once.
<p>
Follow the instructions in the "Unit tests" section installed locally at docs/internals/contributing/writing-code/unit-tests.txt, published online at <a href="https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/#running-the-unit-tests">docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/</a>
This involves running <var>git clone</var> on the django source repo to download the tests. We hope we never have to do this again but in case we get incomprehensible bugs in future, we should be prepared to do so.