s3dgraphy 1.5.2__tar.gz → 1.6.0.dev5__tar.gz

{s3dgraphy-1.5.2/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.5.2
+Version: 1.6.0.dev5
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
@@ -32,10 +32,17 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pandas>=2.0.0
-Requires-Dist: numpy>=1.21.0
 Requires-Dist: lxml>=4.9.0
 Requires-Dist: openpyxl>=3.0.0
 Requires-Dist: networkx>=3.0
+Provides-Extra: rdf
+Requires-Dist: rdflib>=7.0; extra == "rdf"
+Provides-Extra: rdf-embedded
+Requires-Dist: rdflib>=7.0; extra == "rdf-embedded"
+Requires-Dist: pyoxigraph>=0.4; extra == "rdf-embedded"
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.0; extra == "visualization"
+Requires-Dist: plotly>=5.0; extra == "visualization"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -49,12 +56,10 @@ Provides-Extra: docs
 Requires-Dist: sphinx>=5.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Requires-Dist: myst-parser; extra == "docs"
-Provides-Extra: visualization
-Requires-Dist: networkx>=3.0; extra == "visualization"
-Requires-Dist: matplotlib>=3.0; extra == "visualization"
-Requires-Dist: plotly>=5.0; extra == "visualization"
 Provides-Extra: full
-Requires-Dist: s3dgraphy[dev,docs,visualization]; extra == "full"
+Requires-Dist: s3dgraphy[rdf-embedded,visualization]; extra == "full"
+Provides-Extra: all
+Requires-Dist: s3dgraphy[dev,docs,full]; extra == "all"
 Dynamic: license-file
 
 # s3dgraphy
@@ -152,6 +157,75 @@ graph.export_json("stratigraphy.json")
 - **Virtual Archaeology**: Create interactive 3D experiences
 - **Research Integration**: Connect archaeological data with other disciplines
 
+## Mapping JSON files
+
+The `src/s3dgraphy/mappings/` folder contains JSON templates that describe how
+to import data from external tabular sources (SQLite tables from PyArchInit,
+XLSX files from EMdb, generic CSVs, etc.) into an s3dgraphy graph.
+
+Two template files live at the root of the folder for reference:
+
+- `template_pyarchinit_mapping.json` — for SQLite-based tables (PyArchInit-style)
+- `template_emdb_mapping.json` — for XLSX-based tables (EMdb-style)
+
+These templates are NOT loaded automatically by `MappingRegistry`, which only
+scans the `pyarchinit/`, `emdb/`, and `generic/` subdirectories. To use one as
+a starting point, copy it to the appropriate subdirectory and adapt it to your
+table structure.
+
+The templates document the schema inline. In addition to `is_id`,
+`is_description`, `is_attribute`, and `node_type`, 1.6 introduces two new
+optional flags on each `column_mappings` entry:
+
+- `is_filter` — marks the column as a candidate filter. Importers expose these
+  via `get_filter_columns()` so a consumer application can present a dropdown
+  before triggering the import.
+- `filter_required` — when `true`, the consumer is expected to force the user
+  to pick a value (no "All values" option). When `false`, the filter is
+  optional.
+
+Each importer (`PyArchInitImporter`, `MappedXLSXImporter`, `XLSXImporter`) now
+accepts a `filters={col: value, ...}` kwarg with AND semantics, and exposes a
+`get_distinct_values(col)` helper for populating the dropdown. The semantics
+are deliberately library-side and make no assumption about who renders the
+filter UI.
+
+**Full schema reference:**
+[Mapping JSON Schema Reference](https://docs.extendedmatrix.org/projects/s3dgraphy/en/latest/importers/mapping_schema.html)
+documents every key (`table_settings`, `column_mappings`, `relations`) and the
+1.6 filter flags in detail.
+
+### Consumer-side quick start
+
+```python
+from s3dgraphy.importer.pyarchinit_importer import PyArchInitImporter
+
+# 1) Probe the mapping: discover filter columns and their values.
+probe = PyArchInitImporter(
+    filepath="excavation.sqlite",
+    mapping_name="pyarchinit_us_mapping",
+)
+for spec in probe.get_filter_columns():
+    column = spec["column"]
+    label = spec["display_name"]
+    required = spec["filter_required"]
+    values = probe.get_distinct_values(column)
+    print(f"{label} ({'required' if required else 'optional'}): {values}")
+
+# 2) Import only the subset the user picked.
+importer = PyArchInitImporter(
+    filepath="excavation.sqlite",
+    mapping_name="pyarchinit_us_mapping",
+    filters={"sito": "Pompei", "area": "A"},
+)
+graph = importer.parse()
+```
+
+`filters` defaults to `None` (no filtering), so all existing code continues
+to work unchanged. Multiple entries are combined with logical AND; values
+match exactly and case-sensitively. The same flow applies to
+`MappedXLSXImporter` and `XLSXImporter` for XLSX sources.
+
 ## 📖 Documentation
 
 - **[User Guide](https://docs.extendedmatrix.org/projects/s3dgraphy/)** - Complete documentation

{s3dgraphy-1.5.2 → s3dgraphy-1.6.0.dev5}/README.md

@@ -93,6 +93,75 @@ graph.export_json("stratigraphy.json")
 - **Virtual Archaeology**: Create interactive 3D experiences
 - **Research Integration**: Connect archaeological data with other disciplines
 
+## Mapping JSON files
+
+The `src/s3dgraphy/mappings/` folder contains JSON templates that describe how
+to import data from external tabular sources (SQLite tables from PyArchInit,
+XLSX files from EMdb, generic CSVs, etc.) into an s3dgraphy graph.
+
+Two template files live at the root of the folder for reference:
+
+- `template_pyarchinit_mapping.json` — for SQLite-based tables (PyArchInit-style)
+- `template_emdb_mapping.json` — for XLSX-based tables (EMdb-style)
+
+These templates are NOT loaded automatically by `MappingRegistry`, which only
+scans the `pyarchinit/`, `emdb/`, and `generic/` subdirectories. To use one as
+a starting point, copy it to the appropriate subdirectory and adapt it to your
+table structure.
+
+The templates document the schema inline. In addition to `is_id`,
+`is_description`, `is_attribute`, and `node_type`, 1.6 introduces two new
+optional flags on each `column_mappings` entry:
+
+- `is_filter` — marks the column as a candidate filter. Importers expose these
+  via `get_filter_columns()` so a consumer application can present a dropdown
+  before triggering the import.
+- `filter_required` — when `true`, the consumer is expected to force the user
+  to pick a value (no "All values" option). When `false`, the filter is
+  optional.
+
+Each importer (`PyArchInitImporter`, `MappedXLSXImporter`, `XLSXImporter`) now
+accepts a `filters={col: value, ...}` kwarg with AND semantics, and exposes a
+`get_distinct_values(col)` helper for populating the dropdown. The semantics
+are deliberately library-side and make no assumption about who renders the
+filter UI.
+
+**Full schema reference:**
+[Mapping JSON Schema Reference](https://docs.extendedmatrix.org/projects/s3dgraphy/en/latest/importers/mapping_schema.html)
+documents every key (`table_settings`, `column_mappings`, `relations`) and the
+1.6 filter flags in detail.
+
+### Consumer-side quick start
+
+```python
+from s3dgraphy.importer.pyarchinit_importer import PyArchInitImporter
+
+# 1) Probe the mapping: discover filter columns and their values.
+probe = PyArchInitImporter(
+    filepath="excavation.sqlite",
+    mapping_name="pyarchinit_us_mapping",
+)
+for spec in probe.get_filter_columns():
+    column = spec["column"]
+    label = spec["display_name"]
+    required = spec["filter_required"]
+    values = probe.get_distinct_values(column)
+    print(f"{label} ({'required' if required else 'optional'}): {values}")
+
+# 2) Import only the subset the user picked.
+importer = PyArchInitImporter(
+    filepath="excavation.sqlite",
+    mapping_name="pyarchinit_us_mapping",
+    filters={"sito": "Pompei", "area": "A"},
+)
+graph = importer.parse()
+```
+
+`filters` defaults to `None` (no filtering), so all existing code continues
+to work unchanged. Multiple entries are combined with logical AND; values
+match exactly and case-sensitively. The same flow applies to
+`MappedXLSXImporter` and `XLSXImporter` for XLSX sources.
+
 ## 📖 Documentation
 
 - **[User Guide](https://docs.extendedmatrix.org/projects/s3dgraphy/)** - Complete documentation

{s3dgraphy-1.5.2 → s3dgraphy-1.6.0.dev5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.5.2"
+version = "1.6.0.dev5"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -44,11 +44,13 @@ classifiers = [
 ]
 
 dependencies = [
-    "pandas>=2.0.0",
-    "numpy>=1.21.0",
-    "lxml>=4.9.0",
-    "openpyxl>=3.0.0",
-    "networkx>=3.0",
+    # Strict runtime dependencies — directly imported by s3dgraphy core.
+    # Kept minimal: numpy was removed in 1.6.0 (only transitive via pandas;
+    # no direct s3dgraphy code imports numpy).
+    "pandas>=2.0.0",            # used by xlsx_importer, mapping system
+    "lxml>=4.9.0",              # used by graphml importer/exporter
+    "openpyxl>=3.0.0",          # used by xlsx_importer
+    "networkx>=3.0",            # used by temporal/inference_engine.py
 ]
 
 [project.urls]
@@ -60,29 +62,59 @@ Repository = "https://github.com/zalmoxes-laran/s3dgraphy.git"
 "Extended Matrix" = "https://www.extendedmatrix.org"
 Changelog = "https://github.com/zalmoxes-laran/s3dgraphy/blob/main/CHANGELOG.md"
 
+# ─────────────────────────────────────────────────────────────────────────
+# Optional features — pip install s3dgraphy[<extra>]
+#
+# Pattern: each feature that requires extra runtime libraries is opt-in.
+# This keeps the core install small and avoids forcing rdflib/pyoxigraph
+# on consumers that only need GraphML/JSON/xlsx pipelines.
+#
+# Recommended for most users:
+#     pip install s3dgraphy[full]
+# ─────────────────────────────────────────────────────────────────────────
 [project.optional-dependencies]
+rdf = [
+    # RDF export pipeline (RDFExporter → Turtle / N-Triples / JSON-LD / TriG / RDF-XML)
+    # via s3dgraphy.exporter.rdf_exporter. Without this extra, importing
+    # RDFExporter raises ImportError (gracefully handled by exporter/__init__.py).
+    "rdflib>=7.0",
+]
+rdf-embedded = [
+    # RDF export + embedded SPARQL store (no separate server required).
+    # Planned for s3dgraphy v1.6.3+ (SPARQL endpoint read/write workflow).
+    "rdflib>=7.0",
+    "pyoxigraph>=0.4",
+]
+visualization = [
+    # Plotting / network visualization helpers. networkx itself is strict
+    # (used by temporal/inference_engine) so it is NOT listed here to avoid
+    # a duplicate constraint that could confuse pip resolvers.
+    "matplotlib>=3.0",
+    "plotly>=5.0",
+]
 dev = [
     "pytest>=7.0",
-    "pytest-cov", 
+    "pytest-cov",
     "black",
     "flake8",
     "mypy",
     "build",
     "twine",
-    "bump2version"
+    "bump2version",
 ]
 docs = [
     "sphinx>=5.0",
     "sphinx-rtd-theme",
-    "myst-parser"
-]
-visualization = [
-    "networkx>=3.0",
-    "matplotlib>=3.0",
-    "plotly>=5.0"
+    "myst-parser",
 ]
+# Convenience aggregate — installs every runtime feature (RDF + viz)
+# without the dev/docs tooling. The dev/docs/test stacks stay separate
+# so CI-style installs don't pull editor/QA deps.
 full = [
-    "s3dgraphy[dev,docs,visualization]"
+    "s3dgraphy[rdf-embedded,visualization]",
+]
+all = [
+    "s3dgraphy[full,dev,docs]",
 ]
 
 [tool.setuptools.packages.find]