submine 0.1.1__cp312-cp312-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.1.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.2
+Name: submine
+Version: 0.1.1
+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 modular Python library for frequent subgraph mining that provides a unified, safe, and extensible interface over heterogeneous mining algorithms implemented in Python, C/C++, and Java.
+
+The library is designed to support research-grade reproducibility and production-safe execution, while remaining lightweight and backend-agnostic.
+
+## Core Design Principles
+
+* Algorithm-agnostic API
+Users select an algorithm; submine handles format adaptation and execution.
+
+* No redundant graph rewrites
+Input graphs are converted directly into the format required by the selected algorithm.
+
+* Strict input validation & safety
+Resource limits, parameter validation, and hardened subprocess execution are enforced by default.
+
+* Clean extensibility model
+New algorithms can be plugged in without modifying core logic.
+
+## Package Layout
+```
+submine/
+├── api.py                  # Public API entrypoint
+├── errors.py               # Structured exception hierarchy
+├── core/
+│   ├── graph.py            # Canonical graph representation
+│   └── result.py           # Mining result containers
+├── algorithms/
+│   ├── base.py             # Base miner abstraction
+│   ├── gspan.py            # gSpan wrapper / implementation
+│   ├── sopagrami.py        # SoPaGraMi backend wrapper
+│   └── ...
+├── io/
+│   ├── common.py           # Shared readers / writers
+│   ├── transcode.py        # Format detection & conversion
+│   ├── gspan.py            # gSpan I/O
+│   ├── sopagrami.py        # .lg I/O
+│   └── ...
+├── utils/
+│   └── checks.py           # Input validation & resource limits
+└── tests/
+    ├── unit/
+    └── functional/
+```
+
+## Supported Algorithms
+
+| Algorithm | Graph Type         | Backend      | Notes                    |
+| --------- | ------------------ | ------------ | ------------------------ |
+| gSpan     | Multiple graphs    | Python / C++ | Frequent subgraph mining |
+| SoPaGraMi | Single large graph | C++          | Social pattern mining    |
+
+Each algorithm declares:
+
+* required input format,
+* parameter schema,
+* execution strategy (in-process vs subprocess).
+
+## Supported Input Formats
+
+submine accepts graphs in multiple formats and converts them directly into the format required by the selected algorithm:
+
+* Edge list (.txt, .edgelist)
+
+* gSpan datasets (.data, .data.x, .data.N)
+
+* SoPaGraMi .lg
+
+* GEXF (.gexf)
+
+* Format detection is automatic and deterministic.
+
+## Installation
+### Runtime installation
+
+
+```bash
+pip install submine
+
+```
+### Dev installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Basic Usage
+
+```python
+from submine.api import mine_subgraphs
+
+results = mine_subgraphs(
+    data="graph.data",
+    algorithm="gspan",
+    min_support=5
+)
+
+```
+
+For SoPaGraMi:
+```python
+results = mine_subgraphs("citeseer.lg", algorithm="sopagrami", 
+                    min_support=100,
+                    sorted_seeds=4,
+                    dump_images_csv=True, #if you want to dump the images
+                    dump_sample_embeddings=True, #if you want to dump the embeddings, not implemented yet
+                    out_dir= "." # /path/to/dir to save the images and embeddings default is ./sopagrami_result
+                    )
+```
+
+## TODO
+* Include more algorithms
+* Added more utils for cross-usage between other graph/network libraries
+
+# Citation
+
+If you use gspan kindly cite the paper
+
+```
+@inproceedings{yan2002gspan,
+  title={gspan: Graph-based substructure pattern mining},
+  author={Yan, Xifeng and Han, Jiawei},
+  booktitle={2002 IEEE International Conference on Data Mining, 2002. Proceedings.},
+  pages={721--724},
+  year={2002},
+  organization={IEEE}
+}
+```
+
+if you use sopagrami, kindly cite the paper
+
+```
+@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},
+  publisher={Elsevier}
+}
+```
+
+You can cite this implementation as well
+
+```
+@misc{amure_submine,
+  title  = {submine: A Subgraph Mining Library},
+  author = {Amure, Ridwan},
+  year   = {2025},
+  url    = {https://github.com/instabaines/submine}
+}
+```

submine-0.1.1.dist-info/RECORD

@@ -0,0 +1,47 @@
+submine-0.1.1.dist-info/RECORD,,
+submine-0.1.1.dist-info/WHEEL,sha256=735A17gG5ShyLwkIV8AnDG0hqZcskErhdy-3EckFfDc,141
+submine-0.1.1.dist-info/METADATA,sha256=jMDdclv55XPqpJm7qoRrTGbqWx9H19Pu7Z83VqjYzbE,5321
+submine-0.1.1.dist-info/licenses/LICENSE,sha256=KNAADYhXKAIGySYjfCVq6P4ZDhIUFfHxeZFYa3-32ec,1055
+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=7yzUfEyuRuOmGPACFg3AR51UoHkvgiGkE43ceXY5HLA,6739
+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/sopagrami_cpp.cpython-312-darwin.so,sha256=h6JndK0C4OWj0Tns-tVKvnupN1cxPLmHRwxpPvxx718,274192
+submine/algorithms/__init__.py,sha256=2OvRa_DdtsGbE-Yf_FF0Q6XadS9wTSh2mlYfrc6Yl9s,953
+submine/algorithms/gspan.py,sha256=wa3kyEkNGN1GaEq8z4SglL4FUbXvYGkc1CwF96fmugo,5616
+submine/algorithms/gspan_cpp.cpython-312-darwin.so,sha256=0xWYe_-tU-8m2SMLxFwXdVLnzOPaVXYIEfaKNg6X7sQ,188192
+submine/algorithms/sopagrami.py,sha256=GDqPmZ-XRjxEAlzYDpRJTqpxRrNN1ccpP_0_PLPDLX4,9157
+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.1.dist-info/WHEEL

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

submine-0.1.1.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.