netbox-pathways 0.1.0__tar.gz

netbox_pathways-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: netbox-pathways
+Version: 0.1.0
+Summary: NetBox plugin for physical cable plant infrastructure documentation with GIS capabilities
+Author-email: Jonathan Senecal <contact@jonathansenecal.com>
+Project-URL: Homepage, https://github.com/jsenecal/netbox-pathways
+Project-URL: Source, https://github.com/jsenecal/netbox-pathways
+Project-URL: Tracker, https://github.com/jsenecal/netbox-pathways/issues
+Project-URL: Documentation, https://jsenecal.github.io/netbox-pathways/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: djangorestframework-gis>=1.2.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: dev
+Requires-Dist: bumpver; extra == "dev"
+Requires-Dist: pre-commit>=4.0.0; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-django>=4.5.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: zensical; extra == "docs"
+
+# netbox-pathways
+
+> A NetBox plugin for documenting physical cable plant infrastructure with PostGIS integration. Track conduits, aerial spans, structures, and cable routing with geographic data, comparable to SmallWorld or ArcGIS with ArcFM for outside/inside plant documentation.
+
+[![PyPI](https://img.shields.io/pypi/v/netbox-pathways.svg)](https://pypi.org/project/netbox-pathways/)
+[![Python](https://img.shields.io/pypi/pyversions/netbox-pathways.svg)](https://pypi.org/project/netbox-pathways/)
+[![NetBox](https://img.shields.io/badge/NetBox-4.5%2B-success.svg)](https://github.com/netbox-community/netbox)
+[![CI](https://github.com/jsenecal/netbox-pathways/actions/workflows/ci.yml/badge.svg)](https://github.com/jsenecal/netbox-pathways/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jsenecal/netbox-pathways/branch/main/graph/badge.svg)](https://codecov.io/gh/jsenecal/netbox-pathways)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+
+## Features
+
+- **Structures** -- poles, manholes, cabinets, equipment rooms, and more with PostGIS geometry (point or polygon).
+- **Pathways** -- conduits, aerial spans, direct buried, innerducts, cable trays with PostGIS line geometry.
+- **Conduit Banks and Junctions** -- model conduit bank configurations and mid-span Y-tees.
+- **Cable Routing** -- track which NetBox cables traverse which pathways, in sequence.
+- **Pull Sheets** -- printable cable routing documents for field crews.
+- **GeoJSON API** -- standard GeoJSON endpoints for QGIS and other GIS clients.
+- **QGIS Integration** -- style files, project generator, and documentation.
+- **Geometry Editing** -- draw and edit geometries directly in NetBox forms via Leaflet map widgets.
+- **Interactive Map** -- built-in Leaflet map for quick visualization.
+- **Indoor / Outdoor** -- pathways can terminate at structures (outdoor) or NetBox locations (indoor).
+
+## Compatibility
+
+| Plugin version | NetBox version | Python    | PostgreSQL          |
+|----------------|----------------|-----------|---------------------|
+| 0.1.x          | 4.5.3+         | 3.12-3.14 | 16+ with PostGIS 3.4|
+
+## Installation
+
+```bash
+pip install netbox-pathways
+```
+
+In your NetBox `configuration.py`:
+
+```python
+PLUGINS = ["netbox_pathways"]
+
+PLUGINS_CONFIG = {
+    "netbox_pathways": {
+        "srid": 3348,           # REQUIRED -- your EPSG code (see warning below)
+        "map_center_lat": 45.5, # default map center latitude (optional)
+        "map_center_lon": -73.5,# default map center longitude (optional)
+        "map_zoom": 10,         # default map zoom level (optional)
+    },
+}
+```
+
+Run migrations and restart:
+
+```bash
+cd /opt/netbox/netbox
+python manage.py migrate
+python manage.py collectstatic --no-input
+sudo systemctl restart netbox netbox-rq
+```
+
+## Configuration
+
+### SRID is immutable after installation
+
+The `srid` setting defines the coordinate reference system used for **all** geometry columns in the database. It is baked into the database schema at migration time.
+
+**Changing the SRID after data has been loaded WILL CORRUPT YOUR SPATIAL DATA.** PostgreSQL / PostGIS does NOT automatically re-project existing coordinates when the column SRID changes. Geometries will have wrong coordinates in the new CRS with no way to recover them automatically.
+
+Choose your SRID carefully before first deployment. Common choices:
+
+| EPSG    | Name                                          | Notes                                            |
+|---------|-----------------------------------------------|--------------------------------------------------|
+| `4326`  | WGS84 (GPS coordinates, degrees)              | Global, but distorts distances and areas.        |
+| `3857`  | Web Mercator (meters)                         | Used by Google Maps, OSM tiles.                  |
+| `3348`  | NAD83(CSRS) / Statistics Canada Lambert (m)   | Good for Canada.                                 |
+| `2154`  | RGF93 / Lambert-93 (meters)                   | Good for France.                                 |
+| `32632` | WGS84 / UTM zone 32N (meters)                 | Good for central Europe.                         |
+
+If you need to change SRID after deployment, you must manually re-project all geometry data using PostGIS `ST_Transform()` and update the column SRID definitions. This is an advanced DBA operation; back up everything first.
+
+## QGIS quick start
+
+Generate a QGIS project with all layers pre-configured:
+
+```bash
+python manage.py generate_qgis_project \
+    --url https://your-netbox \
+    --token your-api-token
+```
+
+Open the generated `.qgs` file in QGIS. Style files (`.qml`) ship under `static/netbox_pathways/qgis/` and can be loaded via Layer Properties > Style > Load Style.
+
+## REST and GeoJSON API
+
+All resources are exposed under `/api/plugins/pathways/`. GeoJSON variants live under `/api/plugins/pathways/geo/` for direct QGIS / OGR consumption. See [API Examples](https://jsenecal.github.io/netbox-pathways/developer/api-examples/) for full endpoint coverage.
+
+## Documentation
+
+Full documentation: **[jsenecal.github.io/netbox-pathways](https://jsenecal.github.io/netbox-pathways/)**
+
+- [Installation](https://jsenecal.github.io/netbox-pathways/getting-started/installation/)
+- [Configuration](https://jsenecal.github.io/netbox-pathways/getting-started/configuration/)
+- [Concepts](https://jsenecal.github.io/netbox-pathways/user-guide/concepts/)
+- [QGIS Integration](https://jsenecal.github.io/netbox-pathways/user-guide/qgis-integration/)
+- [Architecture](https://jsenecal.github.io/netbox-pathways/developer/architecture/)
+- [GeoJSON API reference](https://jsenecal.github.io/netbox-pathways/reference/geojson-api/)
+
+## Contributing
+
+PRs welcome. Use conventional-commits PR titles (`feat:`, `fix:`, `chore:`, `docs:`, ...) -- release-drafter assembles release notes from them. Run `make setup` after cloning to install dev dependencies and the pre-commit hooks (including the AI-attribution-rejecting `commit-msg` hook).
+
+## License
+
+[Apache License 2.0](LICENSE).

netbox_pathways-0.1.0/README.md

@@ -0,0 +1,115 @@
+# netbox-pathways
+
+> A NetBox plugin for documenting physical cable plant infrastructure with PostGIS integration. Track conduits, aerial spans, structures, and cable routing with geographic data, comparable to SmallWorld or ArcGIS with ArcFM for outside/inside plant documentation.
+
+[![PyPI](https://img.shields.io/pypi/v/netbox-pathways.svg)](https://pypi.org/project/netbox-pathways/)
+[![Python](https://img.shields.io/pypi/pyversions/netbox-pathways.svg)](https://pypi.org/project/netbox-pathways/)
+[![NetBox](https://img.shields.io/badge/NetBox-4.5%2B-success.svg)](https://github.com/netbox-community/netbox)
+[![CI](https://github.com/jsenecal/netbox-pathways/actions/workflows/ci.yml/badge.svg)](https://github.com/jsenecal/netbox-pathways/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jsenecal/netbox-pathways/branch/main/graph/badge.svg)](https://codecov.io/gh/jsenecal/netbox-pathways)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+
+## Features
+
+- **Structures** -- poles, manholes, cabinets, equipment rooms, and more with PostGIS geometry (point or polygon).
+- **Pathways** -- conduits, aerial spans, direct buried, innerducts, cable trays with PostGIS line geometry.
+- **Conduit Banks and Junctions** -- model conduit bank configurations and mid-span Y-tees.
+- **Cable Routing** -- track which NetBox cables traverse which pathways, in sequence.
+- **Pull Sheets** -- printable cable routing documents for field crews.
+- **GeoJSON API** -- standard GeoJSON endpoints for QGIS and other GIS clients.
+- **QGIS Integration** -- style files, project generator, and documentation.
+- **Geometry Editing** -- draw and edit geometries directly in NetBox forms via Leaflet map widgets.
+- **Interactive Map** -- built-in Leaflet map for quick visualization.
+- **Indoor / Outdoor** -- pathways can terminate at structures (outdoor) or NetBox locations (indoor).
+
+## Compatibility
+
+| Plugin version | NetBox version | Python    | PostgreSQL          |
+|----------------|----------------|-----------|---------------------|
+| 0.1.x          | 4.5.3+         | 3.12-3.14 | 16+ with PostGIS 3.4|
+
+## Installation
+
+```bash
+pip install netbox-pathways
+```
+
+In your NetBox `configuration.py`:
+
+```python
+PLUGINS = ["netbox_pathways"]
+
+PLUGINS_CONFIG = {
+    "netbox_pathways": {
+        "srid": 3348,           # REQUIRED -- your EPSG code (see warning below)
+        "map_center_lat": 45.5, # default map center latitude (optional)
+        "map_center_lon": -73.5,# default map center longitude (optional)
+        "map_zoom": 10,         # default map zoom level (optional)
+    },
+}
+```
+
+Run migrations and restart:
+
+```bash
+cd /opt/netbox/netbox
+python manage.py migrate
+python manage.py collectstatic --no-input
+sudo systemctl restart netbox netbox-rq
+```
+
+## Configuration
+
+### SRID is immutable after installation
+
+The `srid` setting defines the coordinate reference system used for **all** geometry columns in the database. It is baked into the database schema at migration time.
+
+**Changing the SRID after data has been loaded WILL CORRUPT YOUR SPATIAL DATA.** PostgreSQL / PostGIS does NOT automatically re-project existing coordinates when the column SRID changes. Geometries will have wrong coordinates in the new CRS with no way to recover them automatically.
+
+Choose your SRID carefully before first deployment. Common choices:
+
+| EPSG    | Name                                          | Notes                                            |
+|---------|-----------------------------------------------|--------------------------------------------------|
+| `4326`  | WGS84 (GPS coordinates, degrees)              | Global, but distorts distances and areas.        |
+| `3857`  | Web Mercator (meters)                         | Used by Google Maps, OSM tiles.                  |
+| `3348`  | NAD83(CSRS) / Statistics Canada Lambert (m)   | Good for Canada.                                 |
+| `2154`  | RGF93 / Lambert-93 (meters)                   | Good for France.                                 |
+| `32632` | WGS84 / UTM zone 32N (meters)                 | Good for central Europe.                         |
+
+If you need to change SRID after deployment, you must manually re-project all geometry data using PostGIS `ST_Transform()` and update the column SRID definitions. This is an advanced DBA operation; back up everything first.
+
+## QGIS quick start
+
+Generate a QGIS project with all layers pre-configured:
+
+```bash
+python manage.py generate_qgis_project \
+    --url https://your-netbox \
+    --token your-api-token
+```
+
+Open the generated `.qgs` file in QGIS. Style files (`.qml`) ship under `static/netbox_pathways/qgis/` and can be loaded via Layer Properties > Style > Load Style.
+
+## REST and GeoJSON API
+
+All resources are exposed under `/api/plugins/pathways/`. GeoJSON variants live under `/api/plugins/pathways/geo/` for direct QGIS / OGR consumption. See [API Examples](https://jsenecal.github.io/netbox-pathways/developer/api-examples/) for full endpoint coverage.
+
+## Documentation
+
+Full documentation: **[jsenecal.github.io/netbox-pathways](https://jsenecal.github.io/netbox-pathways/)**
+
+- [Installation](https://jsenecal.github.io/netbox-pathways/getting-started/installation/)
+- [Configuration](https://jsenecal.github.io/netbox-pathways/getting-started/configuration/)
+- [Concepts](https://jsenecal.github.io/netbox-pathways/user-guide/concepts/)
+- [QGIS Integration](https://jsenecal.github.io/netbox-pathways/user-guide/qgis-integration/)
+- [Architecture](https://jsenecal.github.io/netbox-pathways/developer/architecture/)
+- [GeoJSON API reference](https://jsenecal.github.io/netbox-pathways/reference/geojson-api/)
+
+## Contributing
+
+PRs welcome. Use conventional-commits PR titles (`feat:`, `fix:`, `chore:`, `docs:`, ...) -- release-drafter assembles release notes from them. Run `make setup` after cloning to install dev dependencies and the pre-commit hooks (including the AI-attribution-rejecting `commit-msg` hook).
+
+## License
+
+[Apache License 2.0](LICENSE).

netbox_pathways-0.1.0/netbox_pathways/__init__.py

@@ -0,0 +1,91 @@
+from netbox.plugins import PluginConfig
+
+__version__ = "0.1.0"
+
+
+class NetBoxPathwaysConfig(PluginConfig):
+    name = "netbox_pathways"
+    verbose_name = "NetBox Pathways"
+    description = "Physical cable plant infrastructure documentation with GIS capabilities"
+    version = __version__
+    author = "Jonathan Senecal"
+    author_email = "contact@jonathansenecal.com"
+    base_url = "pathways"
+    required_settings = ["srid"]
+    default_settings = {
+        "map_center_lat": 45.5017,
+        "map_center_lon": -73.5673,
+        "map_zoom": 10,
+        "map_tiles": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
+        "map_max_native_zoom": 19,
+        "map_attribution": "© OpenStreetMap contributors",
+        "map_overlays": [],
+    }
+    django_apps = [
+        "django.contrib.gis",
+        "rest_framework_gis",
+    ]
+
+    # Populated in ready(), consumed by template_content.py
+    _map_config = {}
+
+    def ready(self):
+        from django.conf import settings
+
+        plugin_cfg = settings.PLUGINS_CONFIG.get("netbox_pathways", {})
+        max_zoom = 22
+
+        base_layers = plugin_cfg.get("map_base_layers")
+        if base_layers:
+            tiles = []
+            for layer in base_layers:
+                tile = dict(layer.items())
+                tile.setdefault("maxZoom", max_zoom)
+                tiles.append(tile)
+        else:
+            tiles_url = plugin_cfg.get(
+                "map_tiles",
+                "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
+            )
+            max_native = plugin_cfg.get("map_max_native_zoom", 19)
+            attribution = plugin_cfg.get(
+                "map_attribution",
+                "© OpenStreetMap contributors",
+            )
+            tiles = [
+                {
+                    "name": "Street",
+                    "url": tiles_url,
+                    "maxZoom": max_zoom,
+                    "maxNativeZoom": max_native,
+                    "attribution": attribution,
+                },
+                {
+                    "name": "Satellite",
+                    "url": (
+                        "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
+                    ),
+                    "maxZoom": max_zoom,
+                    "maxNativeZoom": 19,
+                    "attribution": "Esri World Imagery",
+                },
+            ]
+
+        NetBoxPathwaysConfig._map_config = {
+            "baseLayers": tiles,
+            "center": [
+                plugin_cfg.get("map_center_lat", 45.5017),
+                plugin_cfg.get("map_center_lon", -73.5673),
+            ],
+            "zoom": plugin_cfg.get("map_zoom", 10),
+            "minZoom": 1,
+            "maxZoom": max_zoom,
+        }
+
+        super().ready()
+
+        # Register signals
+        from . import signals  # noqa: F401
+
+
+config = NetBoxPathwaysConfig

netbox_pathways-0.1.0/netbox_pathways/api/external_geo.py

@@ -0,0 +1,134 @@
+"""GeoJSON endpoint for reference-mode external map layers.
+
+Resolves geometry by joining through the FK declared in the layer
+registration, transforms to WGS84, applies bbox filtering, and returns
+a standard GeoJSON FeatureCollection.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from django.contrib.gis.db import models as gis_models
+from django.contrib.gis.db.models.functions import Transform
+from django.contrib.gis.geos import Polygon
+from django.db import models as db_models
+from django.http import Http404, JsonResponse
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.views import APIView
+
+from netbox_pathways.api.geo import MAX_GEO_RESULTS
+from netbox_pathways.geo import LEAFLET_SRID
+from netbox_pathways.registry import SUPPORTED_GEO_MODELS, registry
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_geo_column(model, geometry_field: str) -> tuple[str, str]:
+    """Return (fk_field__geo_column, target_model_label) for the FK.
+
+    Raises ValueError if the FK target is not in SUPPORTED_GEO_MODELS.
+    """
+    fk = model._meta.get_field(geometry_field)
+    target = fk.related_model
+    target_label = f"{target._meta.app_label}.{target._meta.model_name}"
+    # Case-insensitive lookup to tolerate label casing
+    for supported_label, geo_col in SUPPORTED_GEO_MODELS.items():
+        if supported_label.lower() == target_label.lower():
+            return f"{geometry_field}__{geo_col}", supported_label
+    raise ValueError(
+        f"FK '{geometry_field}' on {model.__name__} points to {target_label}, which is not in SUPPORTED_GEO_MODELS."
+    )
+
+
+def _build_properties(obj, feature_fields: list[str] | None, model) -> dict:
+    """Build GeoJSON properties dict from model instance."""
+    props: dict = {"id": obj.pk}
+
+    if feature_fields is not None:
+        fields_to_use = feature_fields
+    else:
+        # Auto-detect scalar fields + FK display values
+        fields_to_use = []
+        for f in model._meta.get_fields():
+            if not hasattr(f, "column"):
+                continue  # skip reverse relations, M2M, etc.
+            if f.name in ("id", "pk"):
+                continue  # already handled above
+            if isinstance(f, gis_models.GeometryField):
+                continue  # skip geometry fields
+            if isinstance(f, (db_models.BinaryField, db_models.JSONField)):
+                continue  # skip non-serializable / large fields
+            fields_to_use.append(f.name)
+
+    for fname in fields_to_use:
+        val = getattr(obj, fname, None)
+        # FK → use __str__ of related object
+        if hasattr(val, "pk"):
+            props[fname] = str(val)
+        elif val is not None:
+            props[fname] = val
+        else:
+            props[fname] = None
+    return props
+
+
+class ExternalLayerGeoView(APIView):
+    """Serve GeoJSON for a reference-mode registered layer."""
+
+    permission_classes = [IsAuthenticated]
+
+    def get(self, request, layer_name: str):
+        layer_reg = registry.get(layer_name)
+        if layer_reg is None or layer_reg.source != "reference":
+            raise Http404(f"No reference-mode layer named '{layer_name}'.")
+
+        qs = layer_reg.queryset(request)
+        model = qs.model
+
+        fk_geo_path, _target_label = _resolve_geo_column(
+            model,
+            layer_reg.geometry_field,
+        )
+
+        # Annotate with WGS84 geometry
+        qs = qs.annotate(
+            _geo_4326=Transform(fk_geo_path, LEAFLET_SRID),
+        ).exclude(_geo_4326__isnull=True)
+
+        # Bbox filtering
+        bbox_str = request.query_params.get("bbox", "")
+        if bbox_str:
+            try:
+                w, s, e, n = (float(x) for x in bbox_str.split(","))
+                bbox_poly = Polygon.from_bbox((w, s, e, n))
+                bbox_poly.srid = LEAFLET_SRID
+                qs = qs.filter(_geo_4326__intersects=bbox_poly)
+            except (ValueError, TypeError):
+                pass  # ignore malformed bbox
+
+        qs = qs[:MAX_GEO_RESULTS]
+
+        features = []
+        for obj in qs:
+            geom = obj._geo_4326
+            if geom is None:
+                continue
+            props = _build_properties(obj, layer_reg.feature_fields, model)
+            features.append(
+                {
+                    "type": "Feature",
+                    "geometry": {
+                        "type": geom.geom_type,
+                        "coordinates": geom.coords,
+                    },
+                    "properties": props,
+                }
+            )
+
+        return JsonResponse(
+            {
+                "type": "FeatureCollection",
+                "features": features,
+            }
+        )