educelab-hercdb 0.1.0__tar.gz

educelab_hercdb-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: educelab-hercdb
+Version: 0.1.0
+Summary: Graph database API for Herculaneum data
+Author-email: Mami Hayashida <mami.hayashida@uky.edu>, Seth Parker <c.seth.parker@uky.edu>
+Project-URL: Repository, https://gitlab.com/educelab/educelab-hercdb
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: neo4j>=5.20
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2
+Requires-Dist: prompt-toolkit
+
+# EduceLab Herculaneum Graph Database API
+
+This API is considered a work in progress and can change at any moment.
+
+## Installation
+
+The latest release is available on PyPI:
+
+```shell
+python3 -m pip install educelab-hercdb
+```
+
+## Connect to a server
+
+```python
+from educelab import hercdb
+
+uri = "neo4j://localhost:7687"
+user = "foo"
+password = "bar"
+db = hercdb.connect(uri, user, password)
+if db.verify_connection():
+  print("Connected!")
+```
+
+### Server configuration
+
+If not provided when calling `hercdb.connect()`, this package will attempt to 
+read the URI, username, and password from the configuration file at `~/.hercdb`. 
+This file is expected to be in the [TOML](https://toml.io/) format:
+```toml
+[database]
+uri = "neo4j://localhost:7687"
+username = "foo"
+password = "bar"
+```
+The section header is optional, and only the information from the first section 
+will be read. In the future, sections may be used to differentiate multiple 
+database servers. **Note: In Python 3.10, the configuration file is loaded 
+using `configparser`, which does not support the full TOML syntax.**
+
+Alternatively, the server information can be provided by exporting the following 
+environment variables:
+```shell
+export EDUCEDB_URI='neo4j://localhost:7687'
+export EDUCEDB_USER=foo
+export EDUCEDB_PASSWORD=bar
+```
+Environment variables take priority over the configuration file. 
+
+As a convenience, this package provides the `hercdb.config.request_required()`
+method, which will check for configuration values in the environment and 
+the configuration file and prompt for any which have not been provided:
+```
+>>> hercdb.config.request_required()
+
+Enter URI: neo4j://localhost:7687
+Enter username: foo
+Enter password: 
+```

educelab_hercdb-0.1.0/README.md

@@ -0,0 +1,60 @@
+# EduceLab Herculaneum Graph Database API
+
+This API is considered a work in progress and can change at any moment.
+
+## Installation
+
+The latest release is available on PyPI:
+
+```shell
+python3 -m pip install educelab-hercdb
+```
+
+## Connect to a server
+
+```python
+from educelab import hercdb
+
+uri = "neo4j://localhost:7687"
+user = "foo"
+password = "bar"
+db = hercdb.connect(uri, user, password)
+if db.verify_connection():
+  print("Connected!")
+```
+
+### Server configuration
+
+If not provided when calling `hercdb.connect()`, this package will attempt to 
+read the URI, username, and password from the configuration file at `~/.hercdb`. 
+This file is expected to be in the [TOML](https://toml.io/) format:
+```toml
+[database]
+uri = "neo4j://localhost:7687"
+username = "foo"
+password = "bar"
+```
+The section header is optional, and only the information from the first section 
+will be read. In the future, sections may be used to differentiate multiple 
+database servers. **Note: In Python 3.10, the configuration file is loaded 
+using `configparser`, which does not support the full TOML syntax.**
+
+Alternatively, the server information can be provided by exporting the following 
+environment variables:
+```shell
+export EDUCEDB_URI='neo4j://localhost:7687'
+export EDUCEDB_USER=foo
+export EDUCEDB_PASSWORD=bar
+```
+Environment variables take priority over the configuration file. 
+
+As a convenience, this package provides the `hercdb.config.request_required()`
+method, which will check for configuration values in the environment and 
+the configuration file and prompt for any which have not been provided:
+```
+>>> hercdb.config.request_required()
+
+Enter URI: neo4j://localhost:7687
+Enter username: foo
+Enter password: 
+```

educelab_hercdb-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools >= 62"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src/"]
+include = ["educelab.hercdb"]
+
+[project]
+name = "educelab-hercdb"
+version = "0.1.0"
+dependencies = [
+    "neo4j>=5.20",
+    "numpy>=2.0",
+    "pandas>=2.2",
+    "prompt-toolkit"
+]
+requires-python = ">= 3.10"
+authors = [
+    {name = "Mami Hayashida", email = "mami.hayashida@uky.edu"},
+    {name = "Seth Parker", email = "c.seth.parker@uky.edu"}
+]
+description = "Graph database API for Herculaneum data"
+readme = "README.md"
+classifiers = [
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Operating System :: OS Independent",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Repository = "https://gitlab.com/educelab/educelab-hercdb"
+
+[project.scripts]
+el-hercdb-search = "educelab.hercdb.apps.search:main"

educelab_hercdb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

educelab_hercdb-0.1.0/src/educelab/hercdb/__init__.py

@@ -0,0 +1,3 @@
+from educelab.hercdb import config
+from educelab.hercdb.api import (connect, GraphDBConnection, FlatbedScanType,
+                                 PGSRawType, SpectralRawType)

educelab_hercdb-0.1.0/src/educelab/hercdb/api.py

@@ -0,0 +1,186 @@
+import logging
+from enum import Enum
+
+from neo4j import GraphDatabase
+
+
+class DatasetType(Enum):
+    FlatbedScan = 'FlatbedScanDataset'
+    PGSRaw = 'PGSRaw'
+    SpectralRaw = 'SpectralRaw'
+
+    def __str__(self):
+        return f'{self.value}'
+
+
+FlatbedScanType = DatasetType.FlatbedScan
+PGSRawType = DatasetType.PGSRaw
+SpectralRawType = DatasetType.SpectralRaw
+
+
+class GraphDBConnection:
+    logger = logging.getLogger('educelab.hercdb')
+    uri: str = None
+    user: str = None
+
+    def __init__(self, uri, user, password):
+        self.uri = uri
+        self.user = user
+        self.driver = GraphDatabase.driver(uri, auth=(user, password))
+
+    def __del__(self):
+        self.close()
+
+    def close(self):
+        self.driver.close()
+
+    def verify_connection(self):
+        try:
+            self.driver.verify_connectivity()
+            return True
+        except Exception as e:
+            self.logger.debug('failed to connect', exc_info=e)
+            return False
+
+    def _delete_all(self):
+        records, summary, keys = self.driver.execute_query(
+            """
+            MATCH (n)
+            DETACH DELETE n
+            """,
+            database_="neo4j",
+        )
+
+    def _return_all(self):
+        records, summary, keys = self.driver.execute_query(
+            """
+            MATCH (n)
+            RETURN  n
+            """,
+            database_="neo4j",
+        )
+        self.logger.debug(records)
+        self.logger.debug(summary)
+        self.logger.debug(keys)
+
+    def _node_count(self) -> int:
+        record, keys, summary = self.driver.execute_query(
+            """
+            MATCH (n)
+            RETURN count(n)
+            """,
+            database_="neo4j",
+        )
+        count = record[0]
+        assert isinstance(count, int)
+        return count
+
+    def get_human_readable_name(self, pherc, cornice=None, pezzo=None):
+
+        pherc_n = None
+        corn_n = None
+        pezzo_n = None
+
+        if cornice:
+            records, summary, keys = self.driver.execute_query(
+                """
+                MATCH (ph:PHerc {name: $ph})-[:HAS]->(cr:Cornice {name: $cor})
+                RETURN ph.human_name, cr.human_name            
+                """, ph=pherc, cor=cornice,
+                database_="neo4j",
+            )
+            if records:
+                pherc_n = records[0]["ph.human_name"]
+                corn_n = records[0]["c.human_name"]
+
+        if pezzo is not None:
+            # Currently this is irrelevant since there are no pezzo with "names"
+            records, summary, keys = self.driver.execute_query(
+                """
+                MATCH (ph:PHerc {name: $ph})-[:HAS]->(:Cornice)
+                                                -[:HAS]->(pz:Pezzo {name: $pz})
+                RETURN ph.human_name, pz.human_name            
+                """, ph=pherc, pz=pezzo,
+                database_="neo4j",
+            )
+            if records:
+                pherc_n = records[0]["ph.human_name"]
+                pezzo_n = records[0]["pz.human_name"]
+
+        if not pherc_n:
+            # If there was neither cornice nor pezzo names given
+            records, summary, keys = self.driver.execute_query(
+                """
+                MATCH (ph:PHerc {name: $ph})
+                RETURN ph.human_name
+                """, ph=pherc,
+                database_="neo4j",
+            )
+            if records:
+                pherc_n = records[0]["ph.human_name"]
+
+        return pherc_n, corn_n, pezzo_n
+
+    def list_cornici_pezzi(self, pherc):
+        # Use display names
+        records, summary, keys = self.driver.execute_query(
+            """
+            MATCH (ph:PHerc {human_name: $ph})
+            OPTIONAL MATCH (ph)-[:HAS]-(cr:Cornice)
+            OPTIONAL MATCH (cr)-[:HAS]-(pz:Pezzo)
+            RETURN ph, cr, pz       
+            """, ph=pherc,
+            database_="neo4j",
+        )
+        return records
+
+    def find_datasets(self, ds_type: DatasetType, pherc, cornice=None,
+                      pezzo=None):
+        # Use display names
+        if cornice:
+            records, summary, keys = self.driver.execute_query(
+                """
+                MATCH (ph:PHerc {name: $ph})-[:HAS]-(cr:Cornice {name: $cor})
+                MATCH (cr)<-[:ASSIGNED_TO]-(e:EduceLabID)
+                MATCH (e)<-[:BELONGS_TO]-(n)
+                WHERE $data_t IN LABELS(n)
+                RETURN n
+                """, data_t=str(ds_type), ph=pherc, cor=cornice,
+                database_="neo4j",
+            )
+
+        else:
+            # Pezzo
+            records, summary, keys = self.driver.execute_query(
+                """
+                MATCH (ph:PHerc {name: $ph})-[:HAS]->(:Cornice)
+                                        -[:HAS]->(pz:Pezzo {human_name: $pz})
+                MATCH (pz)<-[:ASSIGNED_TO]-(e:EduceLabID)
+                MATCH (e)<-[:BELONGS_TO]-(n)
+                WHERE $data_t IN LABELS(n)
+                RETURN n
+                """, data_t=str(ds_type), ph=pherc, pz=pezzo,
+                database_="neo4j",
+            )
+
+        properties = []
+        for record in records:
+            dataset = record[0]
+            properties.append(dict(dataset))
+
+        return properties
+
+
+def connect(uri=None, user=None, password=None) -> GraphDBConnection:
+    # use system config values if not provided
+    from educelab.hercdb import config
+    if uri is None:
+        uri = config.uri
+    if user is None:
+        user = config.username
+    if password is None:
+        password = config.password
+
+    # open new connection
+    db = GraphDBConnection(uri, user, password)
+    return db

educelab_hercdb-0.1.0/src/educelab/hercdb/config.py

@@ -0,0 +1,80 @@
+import logging
+import os
+import sys
+from functools import lru_cache
+from getpass import getpass, GetPassWarning
+from pathlib import Path
+
+from prompt_toolkit import prompt
+
+
+@lru_cache(maxsize=2)
+def _load_config():
+    """Load ~/.educedb as a dictionary."""
+    logger = logging.getLogger('educelab.hercdb')
+    cfg_path = Path.home() / '.educedb'
+    if not cfg_path.exists():
+        return None
+
+    if sys.version_info < (3, 11):
+        logger.debug('config backend: configparser')
+        import configparser
+        with cfg_path.open('r') as f:
+            cfg = configparser.ConfigParser()
+            cfg.read_file(f)
+            cfg = {s: dict(cfg.items(s)) for s in cfg.sections()}
+
+    else:
+        logger.debug('config backend: tomllib')
+        import tomllib
+        with cfg_path.open('rb') as f:
+            cfg = tomllib.load(f)
+
+    # return first section if present
+    if isinstance(next(iter(cfg.values())), dict):
+        cfg = next(iter(cfg.values()))
+
+    return cfg
+
+
+def _get_cfg_val(env_key, config_key):
+    """Return a config value from the environment or config file."""
+    # Prefer env val
+    val = os.getenv(env_key, None)
+    if val is not None:
+        return val
+
+    # Load config
+    cfg = _load_config()
+    if cfg is None:
+        _load_config.cache_clear()
+        return None
+
+    return cfg.get(config_key, None)
+
+
+def __getattr__(name):
+    """Stub to avoid attribute errors on this module"""
+    pass
+
+
+# Default properties #
+uri = _get_cfg_val('EDUCEDB_URI', 'uri')
+username = _get_cfg_val('EDUCEDB_USER', 'username')
+password = _get_cfg_val('EDUCEDB_PASSWORD', 'password')
+
+
+def request_required():
+    """Prompt the user to provide required configuration information."""
+    global uri, username, password
+    if uri is None:
+        uri = prompt('Enter URI: ')
+
+    if username is None:
+        username = prompt('Enter username: ')
+
+    if password is None:
+        try:
+            password = getpass('Enter password: ')
+        except GetPassWarning:
+            pass

educelab_hercdb-0.1.0/src/educelab_hercdb.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: educelab-hercdb
+Version: 0.1.0
+Summary: Graph database API for Herculaneum data
+Author-email: Mami Hayashida <mami.hayashida@uky.edu>, Seth Parker <c.seth.parker@uky.edu>
+Project-URL: Repository, https://gitlab.com/educelab/educelab-hercdb
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: neo4j>=5.20
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2
+Requires-Dist: prompt-toolkit
+
+# EduceLab Herculaneum Graph Database API
+
+This API is considered a work in progress and can change at any moment.
+
+## Installation
+
+The latest release is available on PyPI:
+
+```shell
+python3 -m pip install educelab-hercdb
+```
+
+## Connect to a server
+
+```python
+from educelab import hercdb
+
+uri = "neo4j://localhost:7687"
+user = "foo"
+password = "bar"
+db = hercdb.connect(uri, user, password)
+if db.verify_connection():
+  print("Connected!")
+```
+
+### Server configuration
+
+If not provided when calling `hercdb.connect()`, this package will attempt to 
+read the URI, username, and password from the configuration file at `~/.hercdb`. 
+This file is expected to be in the [TOML](https://toml.io/) format:
+```toml
+[database]
+uri = "neo4j://localhost:7687"
+username = "foo"
+password = "bar"
+```
+The section header is optional, and only the information from the first section 
+will be read. In the future, sections may be used to differentiate multiple 
+database servers. **Note: In Python 3.10, the configuration file is loaded 
+using `configparser`, which does not support the full TOML syntax.**
+
+Alternatively, the server information can be provided by exporting the following 
+environment variables:
+```shell
+export EDUCEDB_URI='neo4j://localhost:7687'
+export EDUCEDB_USER=foo
+export EDUCEDB_PASSWORD=bar
+```
+Environment variables take priority over the configuration file. 
+
+As a convenience, this package provides the `hercdb.config.request_required()`
+method, which will check for configuration values in the environment and 
+the configuration file and prompt for any which have not been provided:
+```
+>>> hercdb.config.request_required()
+
+Enter URI: neo4j://localhost:7687
+Enter username: foo
+Enter password: 
+```

educelab_hercdb-0.1.0/src/educelab_hercdb.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/educelab/hercdb/__init__.py
+src/educelab/hercdb/api.py
+src/educelab/hercdb/config.py
+src/educelab_hercdb.egg-info/PKG-INFO
+src/educelab_hercdb.egg-info/SOURCES.txt
+src/educelab_hercdb.egg-info/dependency_links.txt
+src/educelab_hercdb.egg-info/entry_points.txt
+src/educelab_hercdb.egg-info/requires.txt
+src/educelab_hercdb.egg-info/top_level.txt

educelab_hercdb-0.1.0/src/educelab_hercdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

educelab_hercdb-0.1.0/src/educelab_hercdb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+el-hercdb-search = educelab.hercdb.apps.search:main

educelab_hercdb-0.1.0/src/educelab_hercdb.egg-info/requires.txt

@@ -0,0 +1,4 @@
+neo4j>=5.20
+numpy>=2.0
+pandas>=2.2
+prompt-toolkit

educelab_hercdb-0.1.0/src/educelab_hercdb.egg-info/top_level.txt

@@ -0,0 +1 @@
+educelab