migrate poetry -> uv

Author: phfaist

.claude/archive/AGENT_PROMPT_WRITE_TESTS.md

@@ -10,7 +10,7 @@ Tests for the `flm.main` module and its submodules go in `test/main/`. All other
 
 **flm-core** is a Python library implementing *Flexible Latex-like Markup* (FLM): an approximate subset of LaTeX syntax parsed via `pylatexenc` (v3 pre-release) and rendered to multiple output formats (HTML, LaTeX, plain text, Markdown). The codebase is also transpiled to JavaScript via Transcrypt, which constrains Python idioms.
 
-Packages are managed via `poetry`. Run tests with `poetry run python -m pytest test/ -v`.
+Packages are managed via `uv`. Run tests with `uv run python -m pytest test/ -v`.
 
 ## Critical Rules
 
@@ -36,7 +36,7 @@ If you need an "in" check, write `self.assertTrue(x in items)`.
 ### Test Quality Requirements
 
 1. **Exact output matching**: Use `self.assertEqual(result, expected)` with the full expected output. Do NOT use `self.assertTrue(substring in result)` for testing rendered output.
-2. **To get exact outputs**: render the FLM input first by running the code, capture the actual output, then verify it is correct, then use that as the assertEqual expectation. You can run snippets via `poetry run python -c "..."` to see actual outputs before writing assertions.
+2. **To get exact outputs**: render the FLM input first by running the code, capture the actual output, then verify it is correct, then use that as the assertEqual expectation. You can run snippets via `uv run python -c "..."` to see actual outputs before writing assertions.
 3. **Test file naming**: `test/test_<module>.py` for core and feature modules, `test/main/test_main_<submodule>.py` for main submodules.
 4. **One test class per logical group** (e.g. `TestFeatureQuoteRendering`, `TestFeatureQuoteInit`, `TestFeatureQuoteRecomposer`).
 5. **Set `maxDiff = None`** on test classes that compare rendered output.
@@ -166,7 +166,7 @@ Skip these main submodules (they involve filesystem/process operations not suita
 3. **Decide**: if existing tests are already high quality with exact assertions and good coverage, skip to the next module. If they need improvement, **keep the existing tests** and add any additional test cases you deem necessary.  If existing tests are incomplete, add more tests to test other inputs or edge cases that were missed.
 4. **Capture actual outputs** by running the code first:
    ```bash
-   poetry run python -c "
+   uv run python -c "
    from flm.flmenvironment import make_standard_environment
    from flm.stdfeatures import standard_features
    from flm.fragmentrenderer.html import HtmlFragmentRenderer
@@ -177,11 +177,11 @@ Skip these main submodules (they involve filesystem/process operations not suita
    ```
 5. **CHECK THE OUTPUTS**: Make sure that the outputs are indeed expected for the test code you designed.  Flag any suspicious behavior or suspected bug with a comment `# REVIEW: <note>` in the source code.  Only fix the source code itself if the error is a typo or a missing import.  In all other cases, keep the failing test and mark it to be skipped pending code review.
 6. **Write the test file** with exact assertEqual assertions using the captured outputs, for test cases whose outputs match the expected output.
-7. **Run the tests** for that module: `poetry run python -m pytest test/test_<module>.py -v`
+7. **Run the tests** for that module: `uv run python -m pytest test/test_<module>.py -v`
 8. **Fix any failures** — if the expected output doesn't match, re-capture and correct.  Flag suspicious behavior (see point 5.) instead of adapting the test itself to the suspicious behavior.
-9. **Run the full test suite** periodically: `poetry run python -m pytest test/ -v` to check for regressions.
+9. **Run the full test suite** periodically: `uv run python -m pytest test/ -v` to check for regressions.
 10. **When you're finished with the module** — read the module again and identify classes, functions, methods, or attributes that are not sufficiently well tested according to the standards specified here.  If you find any, complete the tests.
-11. **Check also the JS-transpiled tests** — by running `(cd flm-js && poetry run python ./generate_flm_js.py --pylatexenc-src-dir=../../pylatexenc --delete-target-dir --compile-tests && node test-flm-js/runtests.js)`.  If tests fail, identify the failure location and identify its cause. Do not change the test logic. Remove the test only if it is clearly unnecessary. Ask for the user's input if fixing the test involves anything else than minor refactoring to remove a feature not supported by transcrypt. JS output and Python output must be the same (except for string-formatted floating-point numbers).
+11. **Check also the JS-transpiled tests** — by running `(cd flm-js && uv run --group buildjslib python ./generate_flm_js.py --pylatexenc-src-dir=../../pylatexenc --delete-target-dir --compile-tests && node test-flm-js/runtests.js)`.  If tests fail, identify the failure location and identify its cause. Do not change the test logic. Remove the test only if it is clearly unnecessary. Ask for the user's input if fixing the test involves anything else than minor refactoring to remove a feature not supported by transcrypt. JS output and Python output must be the same (except for string-formatted floating-point numbers).
 
 
 ## What to Test Per Module

.github/workflows/deploy-pypi.yml

@@ -13,26 +13,20 @@ jobs:
     strategy:
       matrix:
         python-version: ["3.11"]
-        poetry-version: ["1.4"]
 
     environment: env-deploy-pypi
 
     steps:
       - uses: actions/checkout@v3
 
-      - uses: actions/setup-python@v4
+      - name: 'Set up uv'
+        uses: astral-sh/setup-uv@v5
         with:
+          enable-cache: true
           python-version: '${{ matrix.python-version }}'
 
-      - name: 'Set up poetry - Run image'
-        uses: abatilo/actions-poetry@v2
-        with:
-          poetry-version: '${{ matrix.poetry-version }}'
-
-      - name: 'Poetry Build Package'
-        run: poetry build
-
-      - name: 'Poetry Publish package'
-        run: 'poetry publish -p ${{ secrets.PYPI_API_TOKEN}} -u __token__'
+      - name: 'uv Build Package'
+        run: 'uv build'
 
-    
+      - name: 'uv Publish package'
+        run: 'uv publish --token ${{ secrets.PYPI_API_TOKEN }}'

.github/workflows/tests-ci-js.yml

@@ -18,8 +18,6 @@ jobs:
       matrix:
         python-version:
           - "3.11"
-        poetry-version:
-          - "1.4"
         node-version:
           - "14"
           - "19"
@@ -39,24 +37,23 @@ jobs:
       - name: 'Setting up some node packages'
         run: 'npm i debug'
 
-      # Poetry & Python are needed to transpile Python library
-      - uses: actions/setup-python@v4
+      # uv & Python are needed to transpile Python library
+      - name: 'Set up uv'
+        uses: astral-sh/setup-uv@v5
         with:
+          enable-cache: true
           python-version: '${{ matrix.python-version }}'
 
-      - name: 'Set up poetry - Run image'
-        uses: abatilo/actions-poetry@v2
-
-      - name: 'Poetry Install (with buildjslib)'
-        run: 'poetry install --with buildjslib'
+      - name: 'uv sync (with buildjslib)'
+        run: 'uv sync --group buildjslib'
 
       - name: 'Check out pylatexenc v3 sources'
         working-directory: 'flm-js'
         run: 'git clone https://github.com/phfaist/pylatexenc.git pylatexenc-src --depth=1'
 
       - name: 'Generate LLM JS library'
         working-directory: 'flm-js'
-        run: 'poetry run python ./generate_flm_js.py --pylatexenc-src-dir=./pylatexenc-src/ --compile-tests'
+        run: 'uv run --no-sync python ./generate_flm_js.py --pylatexenc-src-dir=./pylatexenc-src/ --compile-tests'
 
       - name: 'Run JS tests'
         working-directory: 'flm-js'

.github/workflows/tests-ci.yml

@@ -21,24 +21,22 @@ jobs:
           - "3.11"
           - "3.12"
           - "3.13"
-        poetry-version:
-          - "1.4"
         os:
           - 'ubuntu-latest'
 
     runs-on: '${{ matrix.os }}'
 
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+
+      - name: 'Set up uv'
+        uses: astral-sh/setup-uv@v5
         with:
+          enable-cache: true
           python-version: '${{ matrix.python-version }}'
-      - name: 'Set up poetry - Run image'
-        uses: abatilo/actions-poetry@v2
-        with:
-          poetry-version: '${{ matrix.poetry-version }}'
-      - name: 'Poetry Install'
-        run: poetry install -E maincmdl
+
+      - name: 'uv sync'
+        run: 'uv sync --extra maincmdl'
 
       - name: 'Run tests'
-        run: poetry run pytest
+        run: 'uv run --no-sync pytest'

.readthedocs.yaml

@@ -1,8 +1,8 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# See poetry builds on RTD:
-# https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry
+# See uv builds on RTD:
+# https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-uv
 
 # Required
 version: 2
@@ -17,16 +17,16 @@ build:
   jobs:
 
     post_create_environment:
-      # Install poetry
-      # https://python-poetry.org/docs/#installing-manually
-      - 'pip install "poetry>=1.4"'
+      # Install uv
+      # https://docs.astral.sh/uv/getting-started/installation/
+      - 'pip install uv'
 
     post_install:
-      # Install dependencies with 'docs' dependency group
-      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
-      # VIRTUAL_ENV needs to be set manually for now.
-      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
-      - 'VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --extras maincmdl --with builddoc'
+      # Install dependencies with the 'builddoc' dependency group.
+      # '--active' installs into the virtualenv that RTD created for us rather
+      # than into a project-local '.venv'; '--inexact' leaves the packages that
+      # RTD itself put there alone.
+      - 'VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv sync --active --inexact --extra maincmdl --group builddoc'
 
 
 sphinx:

CLAUDE.md

@@ -6,7 +6,7 @@
 
 The codebase is also transpiled to JavaScript via **Transcrypt** (`flm-js/`). This constrains what Python idioms are usable.
 
-Packages are managed via `poetry`.  Prefix test and python-specific calls appropriately, e.g. `poetry run python -m pytest ...`
+Packages are managed via `uv`.  Prefix test and python-specific calls appropriately, e.g. `uv run python -m pytest ...`
 
 ## Structure
 
@@ -120,4 +120,4 @@ Used for forward references (`\ref`, `\eqref`, `\cite`). The mechanism:
 
 ## Documentation
 
-Sphinx docs live in `doc/`. Build with `poetry run sphinx-build -b html doc doc/_build/html`. API docs use `autodoc` directives pulling from source docstrings. User guide pages (overview, standard-syntax, configuration, features, model, lib) are hand-written RST. The build generates `flm-config-json-schema.json` in the HTML output root via a `build-finished` hook in `conf.py`. CLI flags `--validate-config-only` and `--print-config-json-schema` expose schema validation and generation.
+Sphinx docs live in `doc/`. Build with `uv run --group builddoc sphinx-build -b html doc doc/_build/html`. API docs use `autodoc` directives pulling from source docstrings. User guide pages (overview, standard-syntax, configuration, features, model, lib) are hand-written RST. The build generates `flm-config-json-schema.json` in the HTML output root via a `build-finished` hook in `conf.py`. CLI flags `--validate-config-only` and `--print-config-json-schema` expose schema validation and generation.

README.md

@@ -528,14 +528,14 @@ See [the `flm-js` subfolder](flm-js/README.md) for more details.
 One-time setup:
 
 ```bash
-> poetry install --extras maincmdl --with builddoc
+> uv sync --extra maincmdl --group builddoc
 ```
 
 Compile docs:
 
 ```bash
 > cd doc
-doc> poetry run make html
+doc> uv run make html
 ```
 
 ### Build JS lib
@@ -547,13 +547,13 @@ rebuilds in final mode.  Assumes a sibling `pylatexenc/` folder where to get the
 pylatexenc sources.  Run:
 
 ```bash
-(cd flm-js && poetry run python ./generate_flm_js.py --pylatexenc-src-dir=../../pylatexenc --delete-target-dir --compile-tests && node test-flm-js/runtests.js &&  poetry run python ./generate_flm_js.py --pylatexenc-src-dir=../../pylatexenc --delete-target-dir)
+(cd flm-js && uv run --group buildjslib python ./generate_flm_js.py --pylatexenc-src-dir=../../pylatexenc --delete-target-dir --compile-tests && node test-flm-js/runtests.js &&  uv run --group buildjslib python ./generate_flm_js.py --pylatexenc-src-dir=../../pylatexenc --delete-target-dir)
 ```
 
 
 ### Make a JSON schema for config
 
 ```bash
-> poetry run python -m flm --print-config-json-schema >flm-config-json-schema.json
+> uv run python -m flm --print-config-json-schema >flm-config-json-schema.json
 ```
 

doc/conf.py

@@ -16,7 +16,7 @@
 from datetime import datetime
 from pathlib import Path
 _pyproject = toml.load(Path(__file__).resolve().parent.parent / "pyproject.toml")
-_author = ", ".join(_pyproject["tool"]["poetry"]["authors"])
+_author = ", ".join(a["name"] for a in _pyproject["project"]["authors"])
 _year = datetime.now().year
 
 

flm-js/README.md

@@ -15,9 +15,9 @@ read on below.
 The JS version of FLM's core modules is obtained by using the great tool
 [Transcrypt](https://www.transcrypt.org/).
 
-Set up your poetry environment with the 'buildjslib' dependency group:
+Set up your uv environment with the 'buildjslib' dependency group:
 
-    > poetry install --with buildjslib
+    > uv sync --group buildjslib
 
 Check out the pylatexenc sources. (If you've done this in the past, you might
 want to do `git pull` in that directory to get the latest version.)
@@ -28,7 +28,7 @@ want to do `git pull` in that directory to get the latest version.)
 
 Generate the relevant JavaScript FLM Sources by running the build script:
 
-    > poetry run python generate_flm_js.py --pylatexenc-src-dir=./pylatexenc-src/
+    > uv run --group buildjslib python generate_flm_js.py --pylatexenc-src-dir=./pylatexenc-src/
 
 Result: A new folder `flm-js/` with a flat layout of JS modules (with qualified
 names such as `flm.feature.math.js`) that you can import in your code.
@@ -42,5 +42,5 @@ Check the ZooDb sources to get a hang of it.
 To compile and run the tests, you can use the following command (WILL OVERWRITE
 TARGET DIRECTORY `test-flm-js`):
 
-    > poetry run python generate_flm_js.py --pylatexenc-src-dir=./pylatexenc-src/ --delete-target-dir --compile-tests
+    > uv run --group buildjslib python generate_flm_js.py --pylatexenc-src-dir=./pylatexenc-src/ --delete-target-dir --compile-tests
     > node test-flm-js/runtests.js

flm/main/watch.py

@@ -112,8 +112,9 @@ def workflow_postprocess_actions_fn(rendered_content, document, render_context):
                     'targets': d_refs,
                 }
                 s_refs_info_json = json.dumps(d_refs_info, cls=ReprValueFallbackJsonEncoder)
+                s_refs_info_json_insertcode = s_refs_info_json.replace('</script>','<\\/script>')
                 rendered_content = rendered_content + f"""
-<script id="FlmRefsData" type="application/json">{s_refs_info_json.replace('</script>','<\\/script>')}</script>
+<script id="FlmRefsData" type="application/json">{s_refs_info_json_insertcode}</script>
 """
             return rendered_content