RC3: Packaging

- Made places optional
- Doc: Improved some redme links
- MWE: Added steps and corrected typo

README.md

@@ -27,7 +27,8 @@ This installs the package and its dependencies,
 ready for use when activating the environment.
 Learn more about `superblockify` by reading
 the [documentation](https://NERDSITU.github.io/superblockify/)
-or the [minimal working example](scripts/mwe.py).
+or
+the [minimal working example](https://github.com/NERDSITU/superblockify/blob/main/scripts/examples/mwe.py).
 
 ## Development Setup
 
@@ -52,8 +53,10 @@ pip install --no-build-isolation --no-deps -e .
 
 ## Usage
 
-For a quick start there are example scripts in the [`examples/`](scripts/examples/)
-folder and a [minimal working example](scripts/mwe.py).
+For a quick start there are example scripts in
+the [`examples/`](https://github.com/NERDSITU/superblockify/blob/main/scripts/examples/)
+folder and
+a [minimal working example](https://github.com/NERDSITU/superblockify/blob/main/scripts/examples/mwe.py).
 
 ## Logging
 

docs/conf.py

@@ -24,7 +24,7 @@
 project = "superblockify"
 copyright = "2023-2024, Carlson Büth"
 author = "Carlson Büth"
-release = "1.0.0rc1"
+release = "1.0.0rc3"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

pyproject.toml

@@ -66,6 +66,9 @@ namespaces = false
 readme = { file = ["README.md", "LICENSE"] }
 version = { attr = "superblockify._version.__version__" }
 
+[tool.setuptools.package-data]
+superblockify = ["*.cfg"]
+
 # --------------------------------------------------------------------------------------
 # Linting
 # --------------------------------------------------------------------------------------

scripts/mwe.py → scripts/examples/mwe.py

@@ -2,8 +2,6 @@
 
 from superblockify import ResidentialPartitioner
 
-# If you have the whole GHS POP raster, set the path like so:
-# >>> superblockify.config.Config.FULL_RASTER = ...
 
 if __name__ == "__main__":
     part = ResidentialPartitioner(
@@ -17,10 +15,9 @@
     # For large places sufficient memory is required
 
     # Save the preprocessed graph to disk:
-    # part.save(save_graph_copy=True)
-
-    # If loading all previous steps are not needed:
-    # part = sb.ResidentialPartitioner.load("Milan_mwe")
+    # >>> part.save(save_graph_copy=True)
+    # If loading a previously saved graph, all previous steps are not needed:
+    # >>> part = ResidentialPartitioner.load("Salerno_mwe")
 
     part.run(
         calculate_metrics=True,
@@ -31,3 +28,12 @@
     # Save the partitioner to disk, with all attributes, without an extra copy of the
     # graph. The original graph has been cached in the data/graphs folder.
     part.save()
+
+# or
+# >>> import superblockify as sb
+# >>> part = sb.ResidentialPartitioner(...)
+# >>> part.run(...)
+# >>> sb.save_to_gpkg(part)
+
+# If you have the whole GHS POP raster, set the path after importing like so:
+# >>> sb.config.Config.FULL_RASTER = ...

superblockify/_version.py

@@ -1,3 +1,3 @@
 """superblockify package version."""
 
-__version__ = "1.0.0rc1"
+__version__ = "1.0.0rc3"

superblockify/config.py

@@ -10,7 +10,7 @@
 
 import logging.config
 from os import getcwd
-from os.path import join, dirname
+from os.path import join, dirname, exists
 
 from ruamel.yaml import YAML
 
@@ -151,6 +151,23 @@ class Config:  # pylint: disable=too-few-public-methods
         ]
         PLACES_100_CITIES = places["place_lists"]["100_cities_boeing"]["cities"]
         PLACES_GERMANY = places["place_lists"]["germany_by_pop"]["cities"]
+    # see if the file is available
+    if exists(PLACES_FILE):
+        with open(PLACES_FILE, "r", encoding="utf-8") as file:
+            yaml = YAML(typ="safe")
+            places = yaml.load(file)
+            PLACES_GENERAL = [
+                (name, data["query"])
+                for name, data in places["place_lists"]["test_general"][
+                    "cities"
+                ].items()
+            ]
+            PLACES_SMALL = [
+                (name, data["query"])
+                for name, data in places["place_lists"]["test_small"]["cities"].items()
+            ]
+            PLACES_100_CITIES = places["place_lists"]["100_cities_boeing"]["cities"]
+            PLACES_GERMANY = places["place_lists"]["germany_by_pop"]["cities"]
 
     # Plot format
     PLOT_SUFFIX = "pdf"