gitronics 0.5.7__tar.gz → 0.5.8__tar.gz

gitronics-0.5.8/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda"
+}

{gitronics-0.5.7 → gitronics-0.5.8}/Cargo.lock

@@ -390,7 +390,7 @@ dependencies = [
 
 [[package]]
 name = "gitronics"
-version = "0.5.7"
+version = "0.5.8"
 dependencies = [
  "chrono",
  "clap",

{gitronics-0.5.7 → gitronics-0.5.8}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "gitronics"
-version = "0.5.7"
+version = "0.5.8"
 edition = "2024"
 description = "Build MCNP neutronics models from modular components"
 license = "EUPL-1.2"

{gitronics-0.5.7 → gitronics-0.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitronics
-Version: 0.5.7
+Version: 0.5.8
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{gitronics-0.5.7 → gitronics-0.5.8}/docs/usage/build.md

@@ -42,6 +42,26 @@ C ============================================================
 
 Gitronics searches all directories listed in `project_roots` (defined in the configuration) for files referenced by stem name. Any file whose stem (name without extension) matches a key in the configuration is a candidate. This means you can organise your project files into subdirectories however you like, as long as each stem name is unique across all `project_roots`.
 
+## Python API
+
+`build_model` is also available as a Python function for use in scripts and notebooks:
+
+```python
+import gitronics
+
+gitronics.build_model(
+    "configurations/in_vessel_only.yaml",
+    "output/",
+)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `config_path` | `str` or `Path` | Path to the configuration YAML file. |
+| `output_path` | `str` or `Path` | Directory to write `assembled.mcnp` into. |
+
+Raises `RuntimeError` on failure with a descriptive message.
+
 ## Logging
 
 Set the `RUST_LOG` environment variable to control verbosity:

{gitronics-0.5.7 → gitronics-0.5.8}/python/gitronics/__init__.py

@@ -10,9 +10,10 @@ from __future__ import annotations
 
 import sys
 
+from .gitronics import py_build_model as build_model  # type: ignore[import]
 from .gitronics import run  # type: ignore[import]
 
-__all__ = ["run"]
+__all__ = ["build_model", "run"]
 
 
 def _cli_main() -> None:

gitronics-0.5.8/python/gitronics/__main__.py

@@ -0,0 +1,3 @@
+from gitronics import _cli_main
+
+_cli_main()

gitronics-0.5.8/python/gitronics/gitronics.pyi

@@ -0,0 +1,45 @@
+"""Type stubs for the gitronics Rust extension module."""
+
+from pathlib import Path
+
+def run(args: list[str]) -> None:
+    """Run the gitronics CLI with the given argument list.
+
+    This is equivalent to running ``gitronics`` from the command line.
+    ``args[0]`` should be the program name (i.e. ``sys.argv``).
+
+    Args:
+        args: Argument list in ``sys.argv`` format, e.g.
+            ``["gitronics", "build", "config.yaml"]``.
+
+    Raises:
+        RuntimeError: If the command fails.
+    """
+    ...
+
+def py_build_model(config_path: Path | str, output_path: Path | str) -> None:
+    """Assemble an MCNP model from a gitronics configuration file.
+
+    Reads the YAML configuration at *config_path*, resolves all referenced
+    filler models and data-card files, and writes ``assembled.mcnp`` (plus a
+    ``.gitignore``) into *output_path*.
+
+    Args:
+        config_path: Path to the YAML configuration file.
+        output_path: Directory where ``assembled.mcnp`` will be written.
+            The directory must already exist.
+
+    Raises:
+        RuntimeError: If any step of the build fails (e.g. missing file,
+            invalid MCNP syntax, validation error).
+
+    Example::
+
+        import gitronics
+
+        gitronics.build_model(
+            "configurations/baseline.yaml",
+            "output/",
+        )
+    """
+    ...

gitronics-0.5.8/python/tests/test_build_model.py

@@ -0,0 +1,30 @@
+import tempfile
+from pathlib import Path
+
+import gitronics
+import pytest
+
+EXAMPLE_CONFIG = (
+    Path(__file__).parent.parent.parent
+    / "example_project"
+    / "configurations"
+    / "valid_configuration.yaml"
+)
+
+
+def test_build_model_success():
+    with tempfile.TemporaryDirectory() as output_dir:
+        gitronics.build_model(EXAMPLE_CONFIG, output_dir)
+        assert (Path(output_dir) / "assembled.mcnp").exists()
+
+
+def test_build_model_accepts_str_paths():
+    with tempfile.TemporaryDirectory() as output_dir:
+        gitronics.build_model(str(EXAMPLE_CONFIG), output_dir)
+        assert (Path(output_dir) / "assembled.mcnp").exists()
+
+
+def test_build_model_missing_config_raises():
+    with tempfile.TemporaryDirectory() as output_dir:
+        with pytest.raises(RuntimeError):
+            gitronics.build_model("does_not_exist.yaml", output_dir)

gitronics-0.5.8/src/python.rs

@@ -0,0 +1,31 @@
+use std::path::PathBuf;
+
+use pyo3::prelude::*;
+
+use crate::build_model::build_model;
+use crate::run_cli;
+
+#[pyfunction]
+fn run(args: Vec<String>) -> PyResult<()> {
+    use pyo3::exceptions::PyRuntimeError;
+    // Clap exits the process on --help / bad args; that's acceptable.
+    run_cli(args).map_err(|e| PyRuntimeError::new_err(e.to_string()))
+}
+
+/// Build an MCNP model from a gitronics configuration file.
+///
+/// Args:
+///     config_path: Path to the YAML configuration file.
+///     output_path: Directory where the assembled model will be written.
+#[pyfunction]
+fn py_build_model(config_path: PathBuf, output_path: PathBuf) -> PyResult<()> {
+    use pyo3::exceptions::PyRuntimeError;
+    build_model(&config_path, &output_path).map_err(|e| PyRuntimeError::new_err(e.to_string()))
+}
+
+/// Python extension module.
+#[pymodule]
+fn gitronics(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(run, m)?)?;
+    m.add_function(wrap_pyfunction!(py_build_model, m)?)
+}

gitronics-0.5.7/src/python.rs

@@ -1,16 +0,0 @@
-use pyo3::prelude::*;
-
-use crate::run_cli;
-
-#[pyfunction]
-fn run(args: Vec<String>) -> PyResult<()> {
-    use pyo3::exceptions::PyRuntimeError;
-    // Clap exits the process on --help / bad args; that's acceptable.
-    run_cli(args).map_err(|e| PyRuntimeError::new_err(e.to_string()))
-}
-
-/// Python extension module.
-#[pymodule]
-fn gitronics(m: &Bound<'_, PyModule>) -> PyResult<()> {
-    m.add_function(wrap_pyfunction!(run, m)?)
-}