Reorganise Python code using pyproject.toml

Add pyproject.toml (the modern alternative to requirements.txt), making this a proper Python package that can be installed via pip and potentially uploaded to PyPI.

This also loads the files using `importlib.resources` and installs them into the wheel. This means that when you create a wheel using `uv build` it will still be able to load all the opcodes and CSV files.

To avoid moving those resource files in the source repo, the Python build backend (hatchling) is instructed to move them to the right place when building a wheel, and the `resource_root()` function checks in both places so it always works. This is a little hacky but it works.

CI builds source and binary wheels (not actually binary) that can be uploaded to PyPI. If we do upload them then using this project is as simple as

```
uvx riscv_opcodes -c 'rv*'
```

Author: Tim Hutt

.github/workflows/python-app.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12','3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4
@@ -29,20 +29,37 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-pre-commit-
 
-    - name: Install dependencies
-      run: python3 -m pip install pre-commit coverage matplotlib
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        version: "0.8.22"
+
+    - name: Install pre-commit
+      run: uv tool install pre-commit
 
     - name: Run pre-commit
       run: pre-commit run --all-files
 
+    # Generate all output with code coverage. Unfortunately due to limitations in
+    # the `coverage` tool we need to run `riscv_opcodes` as a module.
     - name: Generate
-      run: coverage run ./parse.py -c -chisel -sverilog -rust -latex -spinalhdl -svg -go "rv*" "unratified/rv*"
+      run: uv run -- coverage run -m riscv_opcodes -c -chisel -sverilog -rust -latex -spinalhdl -svg -go "rv*" "unratified/rv*"
 
     - name: Check C output
       run: cat encoding.out.h | cpp
 
     - name: Generate coverage
-      run: coverage xml
+      run: uv run -- coverage xml
 
     - name: Upload coverage
       uses: codecov/codecov-action@v4
+
+    - name: Build wheels
+      run: uv build
+
+    - name: Upload wheels
+      if: matrix.python-version == '3.13'
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist

.github/workflows/tests.yml

@@ -21,23 +21,16 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Cache pip dependencies
-      uses: actions/cache@v3
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
       with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ matrix.python-version }}-coverage
-        restore-keys: |
-          ${{ runner.os }}-pip-${{ matrix.python-version }}-
-
-    - name: Install dependencies
-      run: |
-         pip3 install coverage
+        version: "0.8.22"
 
     - name: Test error outputs
-      run: coverage run -m unittest -b
+      run: uv run -- coverage run -m unittest -b tests/test.py
 
     - name: Generate coverage report
-      run: coverage xml
+      run: uv run -- coverage xml
 
     - name: Upload coverage report
       uses: codecov/codecov-action@v4

.gitignore

@@ -12,3 +12,10 @@ inst.svg
 instr_dict.json
 
 __pycache__/
+
+# Default uv virtual environment location.
+/.venv
+
+# Generated by `coverage` tool.
+/.coverage
+/coverage.xml

.pylintrc

@@ -25,6 +25,9 @@ disable=
     missing-module-docstring,
     missing-function-docstring,
     missing-class-docstring,
+    # Unfortunately pylint doesn't respect py-version when warning
+    # about deprecated items. See https://github.com/pylint-dev/pylint/issues/10608
+    deprecated-class,
 
 # These names are fine when used sensibly. Without listing them here
 # Pylint will complain they are too short.

Makefile

@@ -7,33 +7,34 @@ INSTALL_HEADER_FILES := $(ISASIM_H) $(PK_H) $(ENV_H) $(OPENOCD_H)
 PSEUDO_FLAG := $(if $(PSEUDO),-pseudo,)
 
 
+.PHONY : default
 default: everything
 
-.PHONY: everything encoding.out.h inst.chisel inst.go latex inst.sverilog inst.rs clean install instr-table.tex priv-instr-table.tex inst.spinalhdl pseudo
+.PHONY: everything encoding.out.h inst.chisel inst.go latex inst.sverilog inst.rs clean install instr-table.tex priv-instr-table.tex inst.spinalhdl pseudo test
 
 pseudo:
 	@$(MAKE) PSEUDO=1 everything
 
 everything:
-	@./parse.py  $(PSEUDO_FLAG) -c -go -chisel -sverilog -rust -latex -spinalhdl $(EXTENSIONS)
+	@uv run riscv_opcodes $(PSEUDO_FLAG) -c -go -chisel -sverilog -rust -latex -spinalhdl $(EXTENSIONS)
 
 encoding.out.h:
-	@./parse.py -c $(PSEUDO_FLAG) $(EXTENSIONS)
+	@uv run riscv_opcodes -c $(PSEUDO_FLAG) $(EXTENSIONS)
 
 inst.chisel:
-	@./parse.py -chisel $(PSEUDO_FLAG) $(EXTENSIONS)
+	@uv run riscv_opcodes -chisel $(PSEUDO_FLAG) $(EXTENSIONS)
 
 inst.go:
-	@./parse.py -go $(PSEUDO_FLAG) $(EXTENSIONS)
+	@uv run riscv_opcodes -go $(PSEUDO_FLAG) $(EXTENSIONS)
 
 latex:
-	@./parse.py -latex $(PSEUDO_FLAG) $(EXTENSIONS)
+	@uv run riscv_opcodes -latex $(PSEUDO_FLAG) $(EXTENSIONS)
 
 inst.sverilog:
-	@./parse.py -sverilog $(PSEUDO_FLAG) $(EXTENSIONS)
+	@uv run riscv_opcodes -sverilog $(PSEUDO_FLAG) $(EXTENSIONS)
 
 inst.rs:
-	@./parse.py -rust $(PSEUDO_FLAG) $(EXTENSIONS)
+	@uv run riscv_opcodes -rust $(PSEUDO_FLAG) $(EXTENSIONS)
 
 clean:
 	rm -f inst* priv-instr-table.tex encoding.out.h
@@ -44,9 +45,12 @@ install: everything
 	    cp -f encoding.out.h $$FILE; \
 	done
 
+test:
+	@uv run -m unittest -b tests/test.py
+
 instr-table.tex: latex
 
 priv-instr-table.tex: latex
 
 inst.spinalhdl:
-	@./parse.py -spinalhdl $(PSEUDO_FLAG) $(EXTENSIONS)
+	@uv run riscv_opcodes -spinalhdl $(PSEUDO_FLAG) $(EXTENSIONS)

README.md

@@ -10,21 +10,19 @@ tools and projects like Spike, PK, RISC-V Manual, etc.
 ## Project Structure
 
 ```bash
-├── constants.py    # contains variables, constants and data-structures used in parse.py
-├── encoding.h      # the template encoding.h file
-├── LICENSE         # license file
-├── Makefile        # makefile to generate artifacts
-├── parse.py        # python file to perform checks on the instructions and generate artifacts
-├── README.md       # this file
-├── rv*             # instruction opcode files
-└── unratified      # contains unratified instruction opcode files
+├── extensions             # instruction opcodes
+├── extensions/unratified  # unratified instruction opcodes
+├── encoding.h        # the template encoding.h file
+├── Makefile          # makefile to generate artifacts
+└── src/riscv_opcodes # python files to perform checks on
+                      # the instructions and generate artifacts
 ```
 
 ## File Naming Policy
 
 This project follows a very specific file structure to define the instruction encodings. All files
 containing instruction encodings start with the prefix `rv`. These files can either be present in
-the root directory (if the instructions have been ratified) or the `unratified` directory. The exact
+the `extensions` directory (if the instructions have been ratified) or the `extensions/unratified` directory. The exact
 file-naming policy and location is as mentioned below:
 
 1. `rv_x` - contains instructions common within the 32-bit and 64-bit modes of extension X.
@@ -140,10 +138,11 @@ The following artifacts can be generated using parse.py:
 - inst.spinalhdl : spinalhdl code to decode instructions
 - inst.go : go code to decode instructions
 
-To generate all the above artifacts for all instructions currently checked in, simply run `make` from the root-directory. This should print the following log on the command-line:
+To generate all the above artifacts for all instructions currently checked in, simply run `make` from the root-directory. [`uv`](https://docs.astral.sh/uv/) is required (see [easy installation instructions](https://docs.astral.sh/uv/getting-started/installation/)).
+
+`make` should print the following log on the command-line:
 
 ```
-Running with args : ['./parse.py', '-c', '-go', '-chisel', '-sverilog', '-rust', '-latex', '-spinalhdl', 'rv*', 'unratified/rv*']
 Extensions selected : ['rv*', 'unratified/rv*']
 INFO:: encoding.out.h generated successfully
 INFO:: inst.chisel generated successfully
@@ -165,7 +164,6 @@ make EXTENSIONS='rv*_i rv*_m'
 Which will print the following log:
 
 ```
-Running with args : ['./parse.py', '-c', '-go', '-chisel', '-sverilog', '-rust', '-latex', '-spinalhdl', 'rv32_i', 'rv64_i', 'rv_i', 'rv64_m', 'rv_m']
 Extensions selected : ['rv32_i', 'rv64_i', 'rv_i', 'rv64_m', 'rv_m']
 INFO:: encoding.out.h generated successfully
 INFO:: inst.chisel generated successfully
@@ -181,7 +179,7 @@ If you only want a specific artifact you can use one or more of the following ta
 For example, if you want to generate the `c` based artifact with extensions as shown earlier, you can use the following command:
 
 ```bash
-./parse.py -c rv*_i rv*_m
+uv run riscv_opcodes -c 'rv*_i' 'rv*_m'
 ```
 Which will print the following log:
 
@@ -202,7 +200,6 @@ You can use the `clean` target to remove all artifacts.
 To add a new extension of instructions, create an appropriate `rv*` file based on the policy defined in [File Structure](#file-naming-policy). Run `make` from the root directory to ensure that all checks pass and all artifacts are created correctly. A successful run should print the following log on the terminal:
 
 ```
-Running with args : ['./parse.py', '-c', '-chisel', '-sverilog', '-rust', '-latex', 'rv*', 'unratified/rv*']
 Extensions selected : ['rv*', 'unratified/rv*']
 INFO:: encoding.out.h generated successfully
 INFO:: inst.chisel generated successfully
@@ -216,7 +213,7 @@ Create a PR for review.
 
 ## Enabling Debug logs in parse.py
 
-To enable debug logs in parse.py change `level=logging.INFO` to `level=logging.DEBUG` and run the python command. You will now see debug statements on
+To enable debug logs in `parse.py` change `level=logging.INFO` to `level=logging.DEBUG` and run the python command. You will now see debug statements on
 the terminal like below:
 ```
 DEBUG:: Collecting standard instructions first

pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "riscv-opcodes"
+version = "0.1.0"
+description = "Machine readable information about RISC-V instruction opcodes"
+readme = "README.md"
+requires-python = ">= 3.9"
+dependencies = [
+    "matplotlib>=3.9.0, <4",
+]
+
+[dependency-groups]
+dev = [
+    # Code coverage tool, used in CI.
+    "coverage >=7,<8"
+]
+
+[project.scripts]
+riscv_opcodes = "riscv_opcodes.parse:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel.force-include]
+"extensions" = "riscv_opcodes/extensions"
+"arg_lut.csv" = "riscv_opcodes/arg_lut.csv"
+"causes.csv" = "riscv_opcodes/causes.csv"
+"csrs.csv" = "riscv_opcodes/csrs.csv"
+"csrs32.csv" = "riscv_opcodes/csrs32.csv"
+"encoding.h" = "riscv_opcodes/encoding.h"

src/riscv_opcodes/__init__.py

@@ -0,0 +1,2 @@
+# Mark this directory as a package. This is not actually needed by
+# Python but Pylint gets confused about relative imports without it.

src/riscv_opcodes/__main__.py

@@ -0,0 +1,10 @@
+"""
+This allows running as a module, i.e. `python3 -m riscv_opcodes` which
+we wouldn't normally need, but the `coverage` tool doesn't work on
+installed scripts - you can't do `coverage run riscv_opcodes` because it
+looks for a Python file called `riscv_opcodes` in the current directory.
+"""
+
+from .parse import main
+
+main()

c_utils.py src/riscv_opcodes/c_utils.pyc_utils.py renamed to src/riscv_opcodes/c_utils.py

@@ -2,8 +2,9 @@
 import os
 import pprint
 
-from constants import causes, csrs, csrs32
-from shared_utils import InstrDict, arg_lut
+from .constants import causes, csrs, csrs32
+from .resources import read_text_resource
+from .shared_utils import InstrDict, arg_lut
 
 pp = pprint.PrettyPrinter(indent=2)
 logging.basicConfig(level=logging.INFO, format="%(levelname)s:: %(message)s")
@@ -43,8 +44,7 @@ def make_c(instr_dict: InstrDict):
         mask = ((1 << (end - begin + 1)) - 1) << begin
         arg_str += f"#define INSN_FIELD_{sanitized_name.upper()} {hex(mask)}\n"
 
-    with open(f"{os.path.dirname(__file__)}/encoding.h", "r", encoding="utf-8") as file:
-        enc_header = file.read()
+    enc_header = read_text_resource("encoding.h")
 
     commit = os.popen('git log -1 --format="format:%h"').read()