submine 0.1.2__cp310-cp310-macosx_11_0_arm64.whl

submine/utils/checks.py

@@ -0,0 +1,115 @@
+"""Environment and safety checks for submine.
+
+This module centralizes lightweight validation utilities that protect the
+library from common failure modes (corrupt inputs, missing binaries) and
+from avoidable abuse (e.g., attempting to load arbitrarily large files into
+memory, unsafe subprocess execution defaults).
+
+These are not meant to be a sandbox. They are meant to provide sensible,
+defensive defaults for a publishable OSS library.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+
+DEFAULT_MAX_INPUT_MB = int(os.getenv("SUBMINE_MAX_INPUT_MB", "128"))
+DEFAULT_MAX_INPUT_BYTES = DEFAULT_MAX_INPUT_MB * 1024 * 1024
+
+
+DEFAULT_MAX_LINES = int(os.getenv("SUBMINE_MAX_LINES", "5000000"))  # 5M lines
+DEFAULT_MAX_LINE_BYTES = int(os.getenv("SUBMINE_MAX_LINE_BYTES", "1048576"))  # 1 MiB per line
+
+
+def iter_text_lines(
+    path: str | Path,
+    *,
+    encoding: str = "utf-8",
+    max_lines: int | None = None,
+    max_line_bytes: int | None = None,
+):
+    """Yield decoded lines from *path* with hard limits.
+
+    This is intended for parsers that stream large graph files. It protects
+    against:
+      - extremely long lines (often accidental corruption or malicious inputs)
+      - unbounded files that could consume excessive CPU time
+
+    Notes:
+      - Lines are decoded with ``errors='replace'`` to avoid UnicodeDecodeError.
+      - The returned lines are stripped of trailing ``\n``.
+    """
+    # Resolve limits at call time so test suites (and embedding apps) can
+    # override them via environment variables without requiring a reload.
+    if max_lines is None:
+        max_lines = int(os.getenv("SUBMINE_MAX_LINES", str(DEFAULT_MAX_LINES)))
+    if max_line_bytes is None:
+        max_line_bytes = int(os.getenv("SUBMINE_MAX_LINE_BYTES", str(DEFAULT_MAX_LINE_BYTES)))
+
+    p = assert_regular_file(path)
+    count = 0
+    with p.open("rb") as f:
+        for raw in f:
+            count += 1
+            if count > max_lines:
+                from ..errors import ResourceLimitError
+                raise ResourceLimitError(
+                    f"Refusing to parse {p}: exceeds max line count limit ({max_lines}). "
+                    "Set SUBMINE_MAX_LINES to increase the limit if you trust this input."
+                )
+            if len(raw) > max_line_bytes:
+                from ..errors import ResourceLimitError
+                raise ResourceLimitError(
+                    f"Refusing to parse {p}: line {count} exceeds max line length ({max_line_bytes} bytes). "
+                    "Set SUBMINE_MAX_LINE_BYTES to increase the limit if you trust this input."
+                )
+            yield raw.decode(encoding, errors="replace").rstrip("\n")
+
+def is_tool_available(name: str) -> bool:
+    """Return True if a given executable exists on the system PATH."""
+    return shutil.which(name) is not None
+
+
+def assert_regular_file(path: str | Path, *, must_exist: bool = True) -> Path:
+    """Validate that *path* points to a regular file.
+
+    We reject directories and (by default) require existence. We also resolve
+    symlinks to avoid surprises.
+    """
+    p = Path(path).expanduser()
+    if must_exist and not p.exists():
+        raise FileNotFoundError(f"File does not exist: {p}")
+    if must_exist and not p.is_file():
+        raise ValueError(f"Expected a regular file path, got: {p}")
+    # Resolve to eliminate '..' segments and follow symlinks.
+    return p.resolve()
+
+
+def assert_file_size_under(path: str | Path, *, max_bytes: int = DEFAULT_MAX_INPUT_BYTES) -> None:
+    """Raise if the file exceeds *max_bytes*.
+
+    This is primarily used to protect code paths that necessarily read the full
+    file into memory (e.g., certain bindings).
+    """
+    p = Path(path)
+    try:
+        size = p.stat().st_size
+    except OSError as e:
+        raise OSError(f"Unable to stat file: {p}") from e
+    if size > max_bytes:
+        from ..errors import ResourceLimitError
+        raise ResourceLimitError(
+            f"Refusing to load {p} ({size} bytes): exceeds configured limit of {max_bytes} bytes. "
+            "Set SUBMINE_MAX_INPUT_MB to increase the limit if you trust this input."
+        )
+
+
+def safe_read_text(path: str | Path, *, encoding: str = "utf-8", max_bytes: int = DEFAULT_MAX_INPUT_BYTES) -> str:
+    """Read a text file with a hard cap on bytes."""
+    p = assert_regular_file(path)
+    assert_file_size_under(p, max_bytes=max_bytes)
+    return p.read_text(encoding=encoding, errors="replace")

submine/utils/logging.py

@@ -0,0 +1,41 @@
+"""Logging utilities for submine.
+
+This module configures a simple hierarchical logging setup that
+suppresses log output by default. Users can enable verbose logging
+per algorithm by passing ``verbose=True`` to the constructor. All
+modules within submine should obtain their logger via
+:func:`get_logger` rather than calling :func:`logging.getLogger`
+directly.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """Return a logger with a default configuration.
+
+    If called for the first time this function sets up a root logger
+    with a basic configuration that logs messages with level WARNING and
+    above to stderr. Subsequent calls return child loggers that
+    propagate messages to the root.
+
+    Parameters
+    ----------
+    name: str, optional
+        Name of the logger. If omitted, a root logger is returned.
+
+    Returns
+    -------
+    logging.Logger
+        Configured logger instance.
+    """
+    if not logging.getLogger().handlers:
+        # Configure root logger once
+        logging.basicConfig(
+            level=logging.WARNING,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+    return logging.getLogger(name)

submine-0.1.2.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.2
+Name: submine
+Version: 0.1.2
+Summary: Modular subgraph mining library with unified API
+Keywords: graph-mining,subgraph-mining,gspan,frequent-subgraph-mining
+Author: Ridwan Amure
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Project-URL: Homepage, https://github.com/instabaines/submine
+Project-URL: Repository, https://github.com/instabaines/submine
+Project-URL: Issues, https://github.com/instabaines/submine/issues
+Requires-Python: >=3.9
+Requires-Dist: networkx>=2.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Description-Content-Type: text/markdown
+
+# submine
+
+**submine** is a research‑grade Python library for frequent subgraph mining that provides a unified, safe, and extensible interface over heterogeneous mining algorithms implemented in Python, C++, and Java.
+
+The goal of *submine* is to let users focus on **what** to mine rather than **how** each algorithm expects its input. Users select an algorithm and parameters; *submine* automatically validates inputs, converts graph formats, and executes the backend in a controlled and reproducible manner.
+
+---
+
+## Key Features
+
+* **Algorithm‑centric API**
+  You specify the mining algorithm and parameters; *submine* handles format adaptation and execution.
+
+* **Direct format transcoding (no redundant rewrites)**
+  Input graphs are converted directly into the native format required by the selected algorithm.
+
+* **Multi‑format graph support**
+  Edge lists, gSpan datasets, single‑graph `.lg` files, and GEXF are supported out of the box.
+
+* **Safe and reproducible execution**
+  Parameter validation, deterministic format detection, and hardened subprocess execution are enforced by default.
+
+* **Extensible design**
+  New algorithms can be added via a clean backend interface without modifying core logic.
+
+---
+
+## Supported Algorithms
+
+### gSpan (Frequent Subgraph Mining)
+
+* **Graph type:** Multiple graphs (transactional dataset)
+* **Typical use case:** Discovering frequent substructures across many graphs
+* **Backend:**  C++
+
+The gSpan backend in *submine* is a C++ implementation adapted and extended from the widely used **gBoost / gSpan reference implementations**, with additional input validation, format handling, and Python bindings for safe integration.
+
+### SoPaGraMi (Single‑Graph Pattern Mining)
+
+* **Graph type:** Single large graph
+* **Typical use case:** Social, biological, or information networks
+* **Backend:** C++
+
+SoPaGraMi is used for scalable subgraph mining on a single graph, where frequency is defined structurally rather than transactionally.
+
+---
+
+## Supported Input Formats
+
+*submine* automatically detects the input format and converts it to the format required by the chosen algorithm:
+
+* **Edge lists**: `.txt`, `.edgelist`
+* **gSpan datasets**: `.data`, `.data.x`, `.data.N`
+* **SoPaGraMi graphs**: `.lg`
+* **GEXF**: `.gexf`
+
+Format detection is deterministic and does not rely on user‑supplied flags.
+
+---
+
+## Installation
+
+### Standard installation
+
+```bash
+pip install submine
+```
+
+### Development installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Basic Usage
+
+### gSpan example
+
+```python
+from submine.api import mine_subgraphs
+
+results = mine_subgraphs(
+    data="graphs.data",
+    algorithm="gspan",
+    min_support=5
+)
+```
+
+**Parameters**
+
+* `data` (str or path): Path to the input graph dataset
+* `algorithm` (str): Mining algorithm (`"gspan"`, `"sopagrami"`, …)
+* `min_support` (int): Minimum support threshold (algorithm‑specific semantics)
+
+---
+
+### SoPaGraMi example
+
+```python
+results = mine_subgraphs(
+    data="citeseer.lg",
+    algorithm="sopagrami",
+    min_support=100,
+    sorted_seeds=4,
+    dump_images_csv=True,
+    dump_sample_embeddings=False,
+    out_dir="."
+)
+```
+
+**SoPaGraMi‑specific parameters**
+
+* `min_support` (int): Minimum frequency threshold
+* `sorted_seeds` (int): Seed sorting strategy (implementation‑specific)
+* `dump_images_csv` (bool): Whether to dump pattern images as CSV metadata
+* `dump_sample_embeddings` (bool): Whether to dump sample embeddings (experimental)
+* `out_dir` (str or path): Output directory for results (default: `./sopagrami_result`)
+
+---
+
+## Design Philosophy
+
+* **No algorithm‑specific I/O burden on the user**
+  Users never manually convert graph formats.
+
+* **Minimal assumptions about graph structure**
+  Directed/undirected and labeled/unlabeled graphs are handled at the backend level.
+
+* **Research‑grade transparency**
+  Backends are explicitly documented and citable.
+
+---
+
+## Citation
+
+If you use **gSpan**, please cite:
+
+```bibtex
+@inproceedings{yan2002gspan,
+  title={gspan: Graph-based substructure pattern mining},
+  author={Yan, Xifeng and Han, Jiawei},
+  booktitle={Proceedings of the IEEE International Conference on Data Mining},
+  pages={721--724},
+  year={2002}
+}
+```
+
+If you use **SoPaGraMi**, please cite:
+
+```bibtex
+@article{nguyen2020fast,
+  title={Fast and scalable algorithms for mining subgraphs in a single large graph},
+  author={Nguyen, Lam BQ and Vo, Bay and Le, Ngoc-Thao and Snasel, Vaclav and Zelinka, Ivan},
+  journal={Engineering Applications of Artificial Intelligence},
+  volume={90},
+  pages={103539},
+  year={2020}
+}
+```
+
+To cite this library:
+
+```bibtex
+@misc{amure_submine,
+  title  = {submine: A Unified Subgraph Mining Library},
+  author = {Amure, Ridwan},
+  year   = {2025},
+  url    = {https://github.com/instabaines/submine}
+}
+```

submine-0.1.2.dist-info/RECORD

@@ -0,0 +1,47 @@
+submine/registry.py,sha256=Jr8tbfbU_j5L5waH7gl4dqtrNB0X_boHnu3A0bVMmuo,254
+submine/__init__.py,sha256=tnuVK76tHfOrZPntQLD-iUugR5PyyGGaE0kyrY2VRjI,899
+submine/api.py,sha256=mGy1ynLFyWnj4yv1piDbBkebNE6GEw4FztwhrKsp4Ao,4369
+submine/errors.py,sha256=YaEtNKkN4qpyrbhSLaN3Vkcot6sfG-9atiYPo8HWds8,1112
+submine/core/graph.py,sha256=XZgLuXh4NOKaSGcBPpFoA8ZRvMkNjmWozVRL7xzowUs,6809
+submine/core/__init__.py,sha256=prISqLxgIC4zUO39LDC69AhSrK4tGl1iC0BmKzuxL_A,443
+submine/core/result.py,sha256=t9D1sYYWr-vdVJGw5AX-CSbiuSioVrrmbY3EeT54mX8,3653
+submine/backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+submine/backends/gspan/CMakeLists.txt,sha256=etRcErf0JK9w7xj_OghoFGszpiQooETHPZE4UIu3RvA,1586
+submine/backends/gspan/misc.cpp,sha256=w5Z2XvogkSNqskZezxauvii-1H0lqZ_RWIpEWfQK5LI,4961
+submine/backends/gspan/graph.cpp,sha256=zhtw3vXcOIFk1sZpoIOQUFIey6teLmPvCeQ_2LiD98w,4265
+submine/backends/gspan/gspan.h,sha256=w9rPfrOB1JIi1M1AlD02PKsrELkRwC3uvcFc0jrLIz4,8247
+submine/backends/gspan/dfs.cpp,sha256=sBsixi3CzhmnClbzmFDj9DOYQ-eaeplL3zVIO7q1lhI,2593
+submine/backends/gspan/ismin.cpp,sha256=MKYMYgnMIMaiAKZLIdNjEe7eUQ2E_mGzo6phOcDmiuM,4083
+submine/backends/gspan/gspan.cpp,sha256=9iud5jf23oyUyjNWe_z_r94f48tnqK5EWQceWUfGIgk,21101
+submine/backends/gspan/python_bindings.cpp,sha256=IrOhBJiYjMOa90GEzncxeBZ1VkZ5-wkJHZB-cqNHZsI,3912
+submine/backends/gspan/main.cpp,sha256=ipp3kPAssz-BBu_7rDi6GfPWwKjJfkJYIv74Rl5DH_A,3414
+submine/backends/sopagrami/cpp/CMakeLists.txt,sha256=WXOoHkclzxmcBCyRBe_D-wV1bXM48CQeKioE-ZvR0Rk,1263
+submine/backends/sopagrami/cpp/include/alg.hpp,sha256=D8krOTYxX47DS3ur_2fwyYYROmv1nXuM6rDiMx5spw8,5284
+submine/backends/sopagrami/cpp/include/common/timer.hpp,sha256=h3wUdSJU_tpoXf5NVtmcUj92wBcNgUPUKEuLcCGiz3Q,360
+submine/backends/sopagrami/cpp/src/alg.cpp,sha256=wd8CTdfUS7iemG6OCWn3mNtujJNplaf561Q0SCzynGo,28710
+submine/backends/sopagrami/cpp/src/python_bindings.cpp,sha256=e9OsCPhaFdkBmqTYSVMXLwFTrg2ig0nebw5dKUxtBqM,3356
+submine/backends/sopagrami/cpp/src/main.cpp,sha256=oiI4I73bKqj_IbuNjEI4WHZL8M9pvIVlJwhcGgSGbHA,3197
+submine/backends/sopagrami/cpp/src/dump.cpp,sha256=0knEeEzPQXVOCJhvU3i4ELIfXdeJsTQUG1OTHxVXtN4,8942
+submine/datasets/loaders.py,sha256=USiGS45-5DwshmJsx0f788Pb-471xcB7np31OUzkm5E,4952
+submine/datasets/__init__.py,sha256=JggD0frQ9zZh9iXINpNMGvTkFac1DZa3U-Gf8umvnmE,384
+submine/io/gexf.py,sha256=jdJYTgf3WyLIhIP-8m4b9JJbGGo2_PvAQ1ddwVGKBLU,2695
+submine/io/transcode.py,sha256=9lj5QOZVz1Q6SQTCWGWlxEzjOfVTqFNzFQ026hVotG4,4428
+submine/io/__init__.py,sha256=VAuJCGXE29KGGSq3jHGOV0mtYLS_yMcg_v-7ESHQze4,697
+submine/io/gspan.py,sha256=B49RPwsSurN-rbPJUZppzJ_5hFzGgwBF9UYsTv3h_wI,8499
+submine/io/common.py,sha256=afDqYSBco4DH8vuhRIZd0SKy_AqFPrrSOWNja5Of7lU,4905
+submine/io/sopagrami.py,sha256=qYqZvKpUmSxj8HDzn7IxNnhu11LRFcMX4NCKro4NIpw,4950
+submine/algorithms/gspan_cpp.cpython-310-darwin.so,sha256=Spzdgpwgb0yjWAgKBVVvtuqAAhQ7Fp399zdg6EBsGxc,188080
+submine/algorithms/__init__.py,sha256=2OvRa_DdtsGbE-Yf_FF0Q6XadS9wTSh2mlYfrc6Yl9s,953
+submine/algorithms/gspan.py,sha256=EjAGJCo7Y4XmX_ekJXhqPhAvxuCDJHTvBOviMoZxpds,5662
+submine/algorithms/sopagrami_cpp.cpython-310-darwin.so,sha256=cjDt-KiR_c9E0WjwFY7nPu76_S3snm6NZOOW8xki8qc,274080
+submine/algorithms/sopagrami.py,sha256=AAr7QWDelIGjvRYefLpiu3upsu1hU50XthJxFd7cV1c,9219
+submine/algorithms/base.py,sha256=YW2X021ZfHIhnggwMkzklh5KMdnN1HoQ1XB7MTfwmRk,5381
+submine/utils/logging.py,sha256=zcx-noJ20Cl2sbaH1HZkKSZZyOXMfHB9JRbbVACJpIM,1275
+submine/utils/checks.py,sha256=fFlxFyPNRfhztgoYXzvfaoELzHN8qQOCmuHUaUbLX2E,4519
+submine/utils/__init__.py,sha256=pF9-ISTFv1XH4g7RiVz2Dapt1EdJBUNleJ7mhpELlGA,196
+submine/cli/__init__.py,sha256=k3MAv7_6UTA7O0Kp1FaMBd0veB0I3MNHdOsHql2oYG8,246
+submine/cli/main.py,sha256=VkdlRALYUzSrgMOL3mBpNsrrfgluajvNKbPsScNL-lQ,2555
+submine-0.1.2.dist-info/RECORD,,
+submine-0.1.2.dist-info/WHEEL,sha256=ARvpZEbgFu-cAxZINNemqHWSYlsYgHkQqksAmhPJqFw,141
+submine-0.1.2.dist-info/METADATA,sha256=di2defMFjShQOcIaOc1dAMIZftY52T-qJ978bZ0neZI,5749
+submine-0.1.2.dist-info/licenses/LICENSE,sha256=KNAADYhXKAIGySYjfCVq6P4ZDhIUFfHxeZFYa3-32ec,1055

submine-0.1.2.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 0.11.6
+Root-Is-Purelib: false
+Tag: cp310-cp310-macosx_11_0_arm64
+Generator: delocate 0.13.0
+

submine-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.