Postgres Migration

.flake8

@@ -0,0 +1,24 @@
+# flake8 linter configurations
+# see https://flake8.pycqa.org/en/latest/user/options.html
+
+[flake8]
+# E203 is not PEP8 compliant https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#slices
+# Is excluded from flake8's own config https://flake8.pycqa.org/en/latest/user/configuration.html
+extend-ignore = E203
+max-line-length = 88
+max-doc-length = 88
+per-file-ignores =
+    # rdtools.x.y imported but unused
+    __init__.py:F401
+    # invalid escape sequence '\s'
+    versioneer.py:W605
+exclude =
+    docs,
+    docs/source/*.py,
+    .eggs,
+    .git,
+    .venv,
+    build,
+    fips.py # toremove
+
+    tutorials_and_tools/tutorials_and_tools/*.py

.github/workflows/flake8-linter-matcher.json

@@ -0,0 +1,17 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "flake8",
+      "pattern": [
+        {
+          "regexp": "^(.+):(\\d+):(\\d+): (\\w+) (.+)$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "code": 4,
+          "message": 5
+        }
+      ]
+    }
+  ]
+}

.github/workflows/flake8.yaml

@@ -0,0 +1,31 @@
+name: flake8
+
+on: [pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.12]
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install flake8
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8  # use this version for --diff option
+    - name: Fetch PR target branch
+      run: |
+        git fetch origin $GITHUB_BASE_REF
+    - name: Setup Flake8 output matcher for PR annotations
+      run: echo '::add-matcher::.github/workflows/flake8-linter-matcher.json'
+    - name: Run flake8 
+      run: |
+        flake8 --config=.flake8

.github/workflows/pytest.yml

@@ -1,12 +1,13 @@
 name: pytest
 
 on:
-  push:
-    branches:
-    - main
-    - development
   pull_request:
   workflow_dispatch:
+  # remove test on push, can be restored later
+  # push:
+  #   branches:
+  #   - main
+  #   - development
 
 jobs:
   test:

.gitignore

@@ -1,6 +1,16 @@
+# vscode config
 .vscode
 
+# caches
+__pycache__/
 geogridfusion/__pycache__/
 geogridfusion.egg-info
 
-tests/__pycache__/
+# test caches
+tests/__pycache__/
+
+# documentation build directory
+docs/build/
+
+# build directory
+dist/

README.md

@@ -158,28 +158,35 @@ If you get a which displays a version number then you have installed PostgreSQL.
     postgres (PostgreSQL) 17.4
 
 
-### Verify GeoGridFusion Startup
+### Attempt GeoGridFusion Startup
 
 Start a python environment which has geogridfusion installed. This can be a python interactive shell or jupyter notebook, etc. Run the following code block to see if we can connect to the database.
 
-    # >>> represents a line of python, other lines are output from the program
+    >>> represents a line of python, other lines are output from the program
 
     >>> import geogridfusion
     >>> conn = geogridfusion.start()
+
+    Successfully initialized PostgreSQL cluster at C:\Users\tford\AppData\Roaming\pgsql\geogridfusion-data
     Starting Postgres subprocess...
-    PostgreSQL connection established after 3.22 seconds.
+    PostgreSQL connection established after 1.64 seconds.
+    attempting to create postgis extension
+    Failed to create PostGIS extension: extension "postgis" is not available
+    DETAIL:  Could not open extension control file "C:/Users/tford/AppData/Roaming/pgsql/share/extension/postgis.control": No such file or directory.
+    HINT:  The extension must first be installed on the system where PostgreSQL is running.
 
-    >>> conn
-    <connection object at 0x0000020A67C76460; dsn: 'dbname=postgres user=postgres host=localhost port=5432', closed: 0>
+    ╰─> FeatureNotSupported: extension "postgis" is not available  
+        DETAIL:  Could not open extension control file "C:/Users/tford/AppData/Roaming/pgsql/share/extension/postgis.control": No such file or directory.  
+        HINT:  The extension must first be installed on the system where PostgreSQL is running.  
 
-If geogridfusion.start() returns a connection object then we have successfully connected to the postgres server.
 
+  **This is expected behavior**, we still need to install PostGIS using the directions below.
 
 ## Install Spatial Extensions (PostGIS)
 
 ### Download and move files
 
-Download a postgis binary bundle from [osgeo source](https://download.osgeo.org/postgis/windows/).
+Download a postgis binary bundle from [osgeo source](https://download.osgeo.org/postgis/windows/). **The version must match your postgres version**. I installed Postgres v17.4 (as shown by the ``$ postgres -V`` command from above).
 
 #### Automatic Install
 
@@ -197,51 +204,25 @@ Unzip it and copy the files as described below.
 | share\postgis\* (if it exists)     | C:\Users\YourName\PostgreSQL\share\postgis\                |
 | bin\* (optional tools)             | C:\Users\YourName\PostgreSQL\bin\                          |
 
-### Create Tables
+<!-- ### Create Tables
 
 The final step in setting up the database is creating the tables that will store our data. We can do this by running ``initialize_tables``. Now you will be ready to use geogridfusion.
 
     import geogridfusion
 
     conn = geogridfusion.start()
-    geogridfusion.initialize_tables(conn=conn)
+    geogridfusion.initialize_tables(conn=conn) -->
 
-# First Time Using
+# Using GeoGridFusion
 
-On your first run of GeoGridFusion you will see an output that looks like this. This is normal and displays the configurations GeoGridFusion is using.
+Now that PostGIS is installed we can start using ``GeoGridFusion``. As above, we can import ``GeoGridFusion`` in a Python environment and attenot to connect. You'll see an output that looks like the following on a sucessful startup. If you get an error similar to before, which says PostGIS is not installed or is missing then you have installed PostGIS incorrectly. Go back and repeat the install.
 
     >>> import geogridfusion
     >>> conn = geogridfusion.start()
 
-    The files belonging to this database system will be owned by user "tobin".
-    This user must also own the server process.
-
-    The database cluster will be initialized with locale "en_US.UTF-8".
-    The default database encoding has accordingly been set to "UTF8".
-    The default text search configuration will be set to "english".
-
-    Data page checksums are disabled.
-
-    creating directory /home/tobin/.config/pgsql/geogridfusion-data ... ok
-    creating subdirectories ... ok
-    selecting dynamic shared memory implementation ... posix
-    selecting default max_connections ... 100
-    selecting default shared_buffers ... 128MB
-    selecting default time zone ... America/Denver
-    creating configuration files ... ok
-    running bootstrap script ... ok
-    performing post-bootstrap initialization ... ok
-    syncing data to disk ... ok
-
-
-    Success. You can now start the database server using:
-
-        pg_ctl -D /home/tobin/.config/pgsql/geogridfusion-data -l logfile start
-
-    Successfully initialized PostgreSQL cluster at /home/tobin/.config/pgsql/geogridfusion-data
-    initdb: warning: enabling "trust" authentication for local connections
-    initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.
-
+    Starting Postgres subprocess...
+    PostgreSQL connection established after 2.75 seconds.
+    attempting to create postgis extension
 
 License
 =======

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd