Adding support for uv and updating README.md (#47)

* Adding support for `uv` and updating `README.md`

* Use UV in CI pipeline

Drop requirements.txt now that we have uv lock file and pyproject
Remove release pins in pyproject, since the lock file contains the same information. This lets us use uv to upgrade dependencies easily
Track dependency resolution for route image optional dependencies into the lock file. Only installed when user provides extra arg

* Update uv usage in readme

---------

Co-authored-by: Nick Walker <nick@nickwalker.us>

Author: jyoo980

.github/workflows/github-pages.yml

@@ -36,7 +36,7 @@ jobs:
           cache: pip
 
       - name: Install Python Dependencies
-        run: pip install -r requirements.txt
+        run: pip install uv && uv sync
 
       - name: Check Schedules
         continue-on-error: false
@@ -100,8 +100,7 @@ jobs:
       - name: Install Playwright
         if: steps.cache-route-images.outputs.cache-hit != 'true'
         run: |
-          pip install playwright pillow
-          playwright install chromium
+          uv sync --extra route-images
 
       - name: Generate route OpenGraph images
         if: steps.cache-route-images.outputs.cache-hit != 'true'

.python-version

@@ -0,0 +1 @@
+3.13

Makefile

@@ -23,43 +23,43 @@ $(NEIGHBORHOODS):
 	@wget -c $(NEIGHBORHOODS_URL) -O $@
 
 $(ROUTES_YML): _bin/make_routes_table.py $(ROUTES_GPX_NORMALIZED)
-	python3 $< $(ROUTES_GPX_NORMALIZED) $@
+	uv run python3 $< $(ROUTES_GPX_NORMALIZED) $@
 
 
 routes/geojson/%.geojson: _bin/gpx_to_geojson.py routes/_gpx/%.gpx $(NEIGHBORHOODS)
 	@mkdir -p $(@D)
-	python3 $< --input routes/_gpx/$*.gpx --output $@
+	uv run python3 $< --input routes/_gpx/$*.gpx --output $@
 
 # Batch convert; use when building from scratch (e.g. CI)
 convert-routes:
 	@mkdir -p routes/geojson
-	python3 _bin/gpx_to_geojson.py --input $(foreach raw, $(ROUTE_RAW_GPX_FILES),$(raw))\
+	uv run python3 _bin/gpx_to_geojson.py --input $(foreach raw, $(ROUTE_RAW_GPX_FILES),$(raw))\
 	 	--output $(foreach raw, $(ROUTE_RAW_GPX_FILES),$(patsubst %.gpx, routes/geojson/%.geojson, $(notdir $(raw))))
 
 
 # All routes in one file
 routes/geojson/routes.geojson: _bin/merge_geojson.py $(ROUTE_GEOJSON_FILES)
-	python3 $< $(ROUTE_GEOJSON_FILES) $@
+	uv run python3 $< $(ROUTE_GEOJSON_FILES) $@
 
 routes/gpx/%.gpx: _bin/normalize_gpx.py routes/_gpx/%.gpx
 	@mkdir -p $(@D)
-	python3 $< --input routes/_gpx/$*.gpx --output routes/gpx/$*.gpx
+	uv run python3 $< --input routes/_gpx/$*.gpx --output routes/gpx/$*.gpx
 
 # Batch normalize; use when building from scratch (e.g. CI)
 normalize-routes:
 	@mkdir -p routes/gpx
-	python3 _bin/normalize_gpx.py --input $(foreach raw, $(ROUTE_RAW_GPX_FILES),$(raw))\
+	uv run python3 _bin/normalize_gpx.py --input $(foreach raw, $(ROUTE_RAW_GPX_FILES),$(raw))\
 		--output $(foreach raw, $(ROUTE_RAW_GPX_FILES),$(patsubst routes/_gpx/%, routes/gpx/%,$(raw)))
 
 $(TRANSIT_DATA):
 	_bin/fetch_transit_data.sh
 
 update-locations: _bin/update_location_transit.py $(TRANSIT_DATA_CSV) $(TRANSIT_DATA) $(NEIGHBORHOODS)
-	python3 $<
+	uv run python3 $<
 
 # also generates rcc_weekends.ics
 rcc.ics: _bin/mkical.py $(ROUTES_YML)
-	python3 $<
+	uv run python3 $<
 
 build: rcc.ics $(ROUTES_YML) $(ROUTE_GEOJSON_FILES)
 	bundle exec jekyll build $(JEKYLL_FLAGS)
@@ -78,15 +78,15 @@ check-html:
 	  --cache '{ "timeframe": { "external": "30d" } }'
 
 check-javascript:
-	python3 _bin/check_javascript.py _site
+	uv run python3 _bin/check_javascript.py _site
 
 check-schedules: $(SCHEDULE)
-	python3 _bin/check-schedules.py
+	uv run python3 _bin/check-schedules.py
 
 check: check-images check-html check-javascript check-schedules
 
 og-route-images:
-	python _bin/generate_route_images.py $(if $(URL_BASE_PATH),--base-path $(URL_BASE_PATH),)
+	uv run python _bin/generate_route_images.py $(if $(URL_BASE_PATH),--base-path $(URL_BASE_PATH),)
 
 serve: rcc.ics $(ROUTES_YML) $(ROUTE_GEOJSON_FILES)
 	ls _config.yml | entr -r bundle exec jekyll serve --watch --drafts --host=0.0.0.0 $(JEKYLL_FLAGS)

README.md

@@ -5,12 +5,30 @@
 This repo contains the website for Race Condition Running
   http://raceconditionrunning.com/
 
-Install dependencies with `pip3 install -r requirements.txt` and
-`bundle install`.
+## Building and Developing Locally
 
-To test locally, run `make serve` (requires [`entr`](https://github.com/eradman/entr); install with
-`brew install entr` or `sudo apt install entr`), after which the page will be available at
-[http://localhost:4000](http://localhost:4000).
+You should use virtual environments to isolate dependencies for Python.
+  [`uv`](https://github.com/astral-sh/uv) is a great way to simplify dependency
+  and virtual environment management, and it enables you to use per-project
+  Python versions.
+
+1. Install [`uv`](https://github.com/astral-sh/uv). Run `uv help` to make sure
+your installation was successful.
+2. Run: `uv sync` and `bundle install`.
+3. Install [`entr`](https://github.com/eradman/entr), either via running:
+`brew install entr` (for macOS) or `sudo apt install entr`.
+
+### Running Locally
+
+After you've installed the Python (`uv sync` ),
+  Ruby (`bundle install`) dependencies and `entr` (see section above for commands),
+  run:
+
+> `make serve`
+
+From the root of this directory.
+A successful deployment will serve a local instance of `raceconditionrunning.github.io`
+on [http://localhost:4000](`localhost:4000`).
 
 The entire site is built by `_bin/mkical.py` and Jekyll; the live site is built
 and deployed by a GitHub action and served by GitHub pages.

pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "raceconditionrunning-github-io"
+version = "0.1.0"
+description = "Website for Race Condition Running (RCR)"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "gpxpy",
+    "haversine",
+    "icalendar",
+    "joblib",
+    "pyyaml",
+    "requests",
+    "tqdm",
+]
+
+[project.optional-dependencies]
+route-images = [
+    "playwright",
+    "pillow",
+]