reworking for best practices

Author: MattReimer

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Run linting
+        run: uv run ruff check .

.github/workflows/pypi-publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.11
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

DEVELOPER.md

@@ -4,6 +4,30 @@ It's recommended that you use `RSXML-RiverscapesXML.code-workspace` if you're in
 
 Always work on a branch and use a pull request.
 
+### Prerequisites
+
+- [uv](https://github.com/astral-sh/uv) for dependency management.
+- [pre-commit](https://pre-commit.com/) for git hooks.
+
+### Setup
+
+1. Install dependencies:
+   ```bash
+   uv sync --all-extras --dev
+   ```
+2. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+## Running tests
+
+We use `nox` to run tests across multiple Python versions.
+
+```bash
+nox
+```
+
 ## Running examples locally
 
 In order to run the examples you will need to install `rsxml`. If you want that installed version to be editable, you can use `pip install -e .` from the root rsxml directory.
@@ -12,13 +36,7 @@ In order to run the examples you will need to install `rsxml`. If you want that
 
 There are two scripts to deploy the package to PyPI:
 
-- `build.sh` - builds the package and puts it in `dist/`. This script also does some checking for compliance with PyPI's requirements.
-- `deploy.sh` - Push the package to the PyPI server. This script will prompt you for your PyPI credentials.
+- `build.sh` - builds the package and puts it in `dist/`.
+- `deploy.sh` - Push the package to the PyPI server. This script requires `PYPI_TOKEN` environment variable.
 
-In order to run these scripts, you'll need to install some dependencies:
-
-```bash
-pip install wheel twine
-# On OSX you'll need to install pandoc. (WINDOWS INSTRUCTIONS PENDING)
-brew install pandoc
-```
+The scripts will automatically install `uv` if it is not present.

RSXML-RiverscapesXML.code-workspace

@@ -0,0 +1,61 @@
+{
+  "folders": [
+    {
+      "name": "📦 rsxml",
+      "path": "."
+    },
+  ],
+  "settings": {
+    "terminal.integrated.defaultProfile.linux": "zsh",
+    "[python]": {
+      "editor.tabSize": 4,
+      "editor.formatOnSave": true,
+    },
+    "autopep8.args": [
+      "--max-line-length=240",
+    ],
+    "pylint.args": [
+      "--extension-pkg-whitelist=pygeoprocessing",
+      "--disable=C0301,C0114,C0103,W0719,W0718",
+      "--max-line-length=240"
+    ],
+    "python.terminal.activateEnvironment": true,
+    "python.testing.pytestEnabled": true,
+    "python.testing.unittestEnabled": true,
+    "files.watcherExclude": {
+      "**/*.egg-info/**": true,
+      "**/docs/**": true,
+      "**/*.pytest_cache/**": true,
+      "**/.venv/**": true,
+      "**/__pycache__/**": true
+    },
+    "search.exclude": {
+      "**/*.egg-info/**": true,
+      "**/*.pytest_cache/**": true,
+      "**/.venv/**": true,
+      "**/__pycache__/**": true
+    },
+    "files.exclude": {
+      "**/*.egg-info/**": true,
+      "**/*.pytest_cache/**": true,
+      "**/.venv/**": true,
+      "**/__pycache__/**": true
+    }
+  },
+  // Suggested extensions that will be installed for everyone
+  "extensions": {
+    "recommendations": [
+      "mhutchie.git-graph",
+      "ms-python.autopep8",
+      "ms-python.pylint",
+      "ms-python.python",
+      "ms-python.vscode-pylance",
+      "njpwerner.autodocstring",
+      "redhat.vscode-xml",
+      "unifiedjs.vscode-mdx",
+      "yzhang.markdown-all-in-one",
+      "GitHub.copilot-chat",
+      "GitHub.copilot"
+    ]
+  }
+}

examples/debug/process_debug.py

@@ -10,8 +10,10 @@
 Note: You need to install psutil and matplotlib `pip install psutil matplotlib` for this to work.
 
 """
-from time import sleep
+
 import tempfile
+from time import sleep
+
 from rsxml import Logger, debug
 
 
@@ -21,27 +23,26 @@ def my_work_method(some_text_arg: str):
     Args:
         some_text_arg (str): _description_
     """
-    log = Logger('my_work_method')
+    log = Logger("my_work_method")
     log.info(some_text_arg)
     sleep(10)
 
 
-if __name__ == '__main__':
-    logmain = Logger('main')
+if __name__ == "__main__":
+    logmain = Logger("main")
 
     # Usully you'd get these from argparse
-    SOME_TEXT_ARG = 'This is some text'
+    SOME_TEXT_ARG = "This is some text"
     DEBUG = True
 
     # Temporary files are just for this example
-    with tempfile.NamedTemporaryFile(suffix='.csv') as f:
-
+    with tempfile.NamedTemporaryFile(suffix=".csv") as f:
         # Here we make a choice to either run our work method normally or in debug mode
         if DEBUG is True:
             # Do the import here so it doesn't cause any errors if we're not debugging
             retcode, max_obj = debug.thread_run(my_work_method, f.name, SOME_TEXT_ARG)
             # It returns some useful information
-            logmain.info('Return code: {}, [Max process usage] {}'.format(retcode, max_obj))
+            logmain.info("Return code: {}, [Max process usage] {}".format(retcode, max_obj))
         else:
             my_work_method(SOME_TEXT_ARG)
 

examples/debug/timers.py

@@ -6,39 +6,41 @@
 to time how long it takes to do something and then write the results to a csv file.
 
 """
-from time import sleep
-import tempfile
+
 import sqlite3
-from rsxml.debug import Timer, LoopTimer, TimerBuckets, TimerWaypoints
+import tempfile
+from time import sleep
+
 from rsxml import Logger
+from rsxml.debug import LoopTimer, Timer, TimerBuckets, TimerWaypoints
 
 
 def simple():
     """
     Basic Timer
 
-    This is a really simple timer with a date subtraction. 
+    This is a really simple timer with a date subtraction.
     """
-    log = Logger('Simple Timer')
+    log = Logger("Simple Timer")
     # Here is a basic timer. Define it and then call elapsed() to get the time
     _tmr = Timer()
     sleep(1)
 
-    log.info(f'Timer: {_tmr.elapsed()}')
+    log.info(f"Timer: {_tmr.elapsed()}")
     # [info] [Simple Timer] Timer: 1.0054419169900939
 
-    log.info(f'Timer: {_tmr.toString()}')
+    log.info(f"Timer: {_tmr.toString()}")
     # [info] [Simple Timer] Timer: 1.0 seconds
 
 
 def loop_timer():
     """
     Loop Timer
 
-    Loop timers are useful for debugging why for loops are taking so long. 
+    Loop timers are useful for debugging why for loops are taking so long.
     """
-    log = Logger('Loop Timer')
-    _lt = LoopTimer('My Loop Timer', log)
+    log = Logger("Loop Timer")
+    _lt = LoopTimer("My Loop Timer", log)
     for _i in range(10):
         _lt.tick()  # Signal to the loop timer that one iteration has happened
         _lt.progprint()  # print the current status of the loop timer continuously to the loop
@@ -60,19 +62,19 @@ def timer_buckets(csv_file: str):
     everything inside the with statement will be counted as part of the timer.
     """
     _tmr_buckets = TimerBuckets(table_name="debug_table", csv_path=csv_file)
-    conn = sqlite3.connect(':memory:')
+    conn = sqlite3.connect(":memory:")
 
     for i in range(10):
-        arbitrary_columns = {'something': i, 'something_else': f"KEY {i}"}
+        arbitrary_columns = {"something": i, "something_else": f"KEY {i}"}
         _tmr_buckets.tick(arbitrary_columns)
 
-        with TimerBuckets('key1'):
+        with TimerBuckets("key1"):
             sleep(0.2)
 
-        with TimerBuckets('key1'):
+        with TimerBuckets("key1"):
             sleep(0.1)
 
-        with TimerBuckets('key2'):
+        with TimerBuckets("key2"):
             sleep(0.15)
 
     _tmr_buckets.write_csv(csv_file)
@@ -98,19 +100,19 @@ def timer_waypoints():
     Waypoints are a way to track the time between points in your code.
     Think of them like lap markers.
     """
-    log = Logger('Timer Waypoints')
-    log.setlevel('DEBUG')
+    log = Logger("Timer Waypoints")
+    log.setlevel("DEBUG")
 
     _tmr_waypoints = TimerWaypoints()
 
     sleep(1)
-    _tmr_waypoints.timer_break('first thing')
+    _tmr_waypoints.timer_break("first thing")
 
     sleep(3)
-    _tmr_waypoints.timer_break('second thing')
+    _tmr_waypoints.timer_break("second thing")
 
     sleep(2)
-    _tmr_waypoints.timer_break('third thing')
+    _tmr_waypoints.timer_break("third thing")
 
     log.info(_tmr_waypoints.toString())
 
@@ -128,7 +130,7 @@ def timer_waypoints():
     simple()
     loop_timer()
 
-    with tempfile.NamedTemporaryFile(suffix='.csv') as f:
+    with tempfile.NamedTemporaryFile(suffix=".csv") as f:
         timer_buckets(f.name)
 
     timer_waypoints()