Merge pull request #23 from hotosm/feat/remove-sqlalchemy

Remove SQLAlchemy and GeoAlchemy

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,7 +7,8 @@ assignees: ""
 ---
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. Ex. I'm always
+frustrated when [...]
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.

.pre-commit-config.yaml

@@ -29,7 +29,8 @@ repos:
           [
             --ignore-unknown,
             --no-error-on-unmatched-pattern,
-            "!chart/**",
+            "!fmtm-splitter/fmtm-splitter_osm_buildings/**",
+            "!postgis_snippets/**",
             "!CHANGELOG.md",
             "!tests/testdata/*",
           ]
@@ -38,4 +39,15 @@ repos:
     rev: v0.38.0
     hooks:
       - id: markdownlint
-        args: [--fix, --ignore, CHANGELOG.md, --ignore, LICENSE.md]
+        args:
+          [
+            --fix,
+            --ignore,
+            CHANGELOG.md,
+            --ignore,
+            LICENSE.md,
+            --ignore,
+            postgis_snippets/**/*.md,
+            --ignore,
+            fmtm_splitter/fmtm-splitter_osm_buildings/*.md,
+          ]

CONTRIBUTING.md

@@ -20,7 +20,7 @@ complications with other developers. The old free software joke is
 "patches are better than bug reports" is how we contribute to the
 community of people involved with this project.
 
-# If you are reporting a problem
+## If you are reporting a problem
 
 - Describe exactly what you were trying to achieve, what you did, what you
   expected to happen and what did happen instead. Include relevant information
@@ -32,15 +32,15 @@ community of people involved with this project.
   keeps issues small and manageable and makes it much easier to follow through
   and make sure each problem is taken care of.
 
-## Documentation
+### Documentation
 
 Project documentation should be in [Markdown
 format](https://www.markdownguide.org/), and in a _docs_
 subdirectory. While it is possible to use HTML in Markdown documents
 for tables and images, it is prefered to use the Markdown style as
 it's much easier to read.
 
-## Coding Style
+### Coding Style
 
 Python enforces a certain amount of style due to indent levels. Unlike
 C/C++, we don't have to worry about curly braces. It is prefered that

README.md

@@ -63,32 +63,15 @@ To install fmtm-splitter, you can use pip. Here are two options:
 - Latest on PyPi:
   `pip install fmtm-splitter`
 
-## Using the Container Image
+## Splitting Types
 
-- fmtm-splitter scripts can be used via the pre-built container images.
-- These images come with all dependencies bundled, so are simple to run.
-
-Run a specific command:
-
-```bash
-docker run --rm -v $PWD:/data ghcr.io/hotosm/fmtm-splitter:latest fmtm-splitter <flags>
-```
-
-Run interactively (to use multiple commands):
-
-```bash
-docker run --rm -it -v $PWD:/data ghcr.io/hotosm/fmtm-splitter:latest
-```
-
-> Note: the output directory should always be /data/... to persist data.
-
-## Split By Square
+### Split By Square
 
 The default is to split the polygon into squares. The default
 dimension is 50 meters, but that is configurable. The outer square are
 clipped to the AOI boundary.
 
-## Split By Feature
+### Split By Feature
 
 The split by feature uses highway data extracted from OpenStreetMap,
 and uses it to generate non square task boundaries. It can also be
@@ -97,12 +80,77 @@ size.
 
 ![Split By Feature](https://github.com/hotosm/fmtm-splitter/blob/main/docs/images/Screenshot%20from%202023-08-06%2018-26-34.png)
 
-## Custom SQL query
+### Custom SQL query
 
 It is also possible to supply a custom SQL query to generate the
 tasks.
 
-## The fmtm-splitter program
+## Usage In Code
+
+- Either the FMTMSplitter class can be used directly, or the wrapper/
+  helper functions can be used for splitting.
+
+By square:
+
+```python
+import json
+from fmtm_splitter.splitter import split_by_square
+
+aoi = json.load("/path/to/file.geojson")
+
+split_features = split_by_square(
+    aoi,
+    meters=100,
+)
+```
+
+The FMTM splitter algorithm:
+
+```python
+import json
+from fmtm_splitter.splitter import split_by_sql
+
+aoi = json.load("/path/to/file.geojson")
+osm_extracts = json.load("/path/to/file.geojson")
+db = "postgresql://postgres:postgres@localhost/postgres"
+
+split_features = split_by_sql(
+    aoi,
+    db,
+    num_buildings=50,
+    osm_extract=osm_extracts,
+)
+```
+
+### Database Connections
+
+- The db parameter can be a connection string to start a new connection.
+- Or an existing database connection can be reused.
+- To do this, the psycopg2 driver connection needs to be passed:
+
+SQLAlchemy example:
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+# Creates a SQLAlchemy Session object
+engine = create_engine("postgresql://postgres:postgres@localhost/postgres")
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+db = SessionLocal()
+
+psycopg2_connection = db.connection()
+
+# Then pass this object as the db param
+split_features = split_by_sql(
+    aoi,
+    psycopg2_connection,
+    num_buildings=50,
+    osm_extract=osm_extracts,
+)
+```
+
+## Usage Via CLI
 
 Options:
 
@@ -131,3 +179,22 @@ fmtm-splitter -v -b AOI -s PG:colorado
 # And OUTFILE is a MultiPolygon output file,which defaults to fmtm.geojson
 # The task splitting defaults to squares, 50 meters across
 ```
+
+### Using the Container Image
+
+- fmtm-splitter scripts can be used via the pre-built container images.
+- These images come with all dependencies bundled, so are simple to run.
+
+Run a specific command:
+
+```bash
+docker run --rm -v $PWD:/data ghcr.io/hotosm/fmtm-splitter:latest fmtm-splitter <flags>
+```
+
+Run interactively (to use multiple commands):
+
+```bash
+docker run --rm -it -v $PWD:/data ghcr.io/hotosm/fmtm-splitter:latest
+```
+
+> Note: the output directory should always be /data/... to persist data.

docs/api.md

@@ -1,6 +1,6 @@
-## API Docs for fmtm-splitter
+# API Docs for fmtm-splitter
 
-# fmtm_splitter.py
+## fmtm_splitter.py
 
 ::: fmtm_splitter.splitter.FMTMSplitter
 options: