ruby_pymill 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c88e00a96d006073f8007aa6395eea1ecb5ccecf530430e9e73b288cb1df18d
-  data.tar.gz: da982b4b979d75075f5d1ce914feb8e79f0844441f18f4d1f2dd2b34e4502517
+  metadata.gz: c2419632f9e7eb3cbb8cf35cd28fa922da156e5487de259cf16ea2eec1471088
+  data.tar.gz: c43e0a5ef36b8be315d41a157589e1d4f5298a2dfa1bc52f9a4f1e56dc107afd
 SHA512:
-  metadata.gz: bdb19766137d960b14a59513b522e65ea11147c940e708969a7a63a19500920c4880d341bcdb694eed013a8f92a6eaaee546cefd6d293d9fb6cf77ab620eabec
-  data.tar.gz: 7d263d39baae7f1055134014f2a6babeb76a931ac3bf51b6bcb47cc053770ec224e6d71701abc337e8647a9ecf08124dba30e1f49d4ac35be68a51f6c116b416
+  metadata.gz: 63f499bd9dce06e1728c26fed3f39ad1be2c00e9dd97007580008a4b8a493d8107f6d04849e310528a0ffec653cf5c6a4451fc518bf16232babb04a0f22e26d5
+  data.tar.gz: d564e1b1b6d23596a6b1708b7d39ffe72058799d1f4912cd55ad006bbab96f444c61969abe3b18b686ae55646df0e811b8edb0080eee3cf920995173fc14b312

data/README.md

@@ -1,6 +1,10 @@
 # RubyPyMill
 Running Notebooks the Ruby Way — RubyPyMill and the Art of PoC Automation
 
+RubyPyMill bridges Ruby orchestration with Python's Jupyter notebook execution ecosystem.
+
+**RubyPyMill v0.3.0 introduces the experimental Ruby API.**
+
 ## Background and Purpose
 RubyPyMill is a lightweight runner and automation starter that allows Ruby
 to control Papermill (a Python Notebook runner).
@@ -26,6 +30,7 @@ RubyPyMill enables reproducible notebook execution from the Ruby ecosystem.
 “Ruby aims to connect people with people, and tools with tools.”  
 — Yukihiro “Matz” Matsumoto
 
+
 ## Project Structure
 | Directory | Description |
 |----------|-------------|
@@ -36,6 +41,15 @@ RubyPyMill enables reproducible notebook execution from the Ruby ecosystem.
 | py/ | Python-side environment (Papermill execution) |
 | examples/ | Example notebooks, parameters, and outputs |
 
+## Installation
+RubyPyMill is distributed as a RubyGem:
+
+```bash
+gem install ruby_pymill
+```
+> Note: RubyPyMill executes Jupyter notebooks via Papermill, so a Python environment is required.
+
+
 ## Setup
 
 ### Ruby
@@ -67,6 +81,19 @@ bundle exec ruby bin/ruby_pymill exec <input.ipynb> \
   [--dry-run]
 ```
 
+### Windows (PowerShell)
+
+PowerShell does not support `\` for line continuation.
+Use backticks (`) or run the command in a single line.
+
+```powershell
+bundle exec ruby bin/ruby_pymill exec examples/notebooks/lang_radar.ipynb `
+  --output examples/outputs/lang_radar_out.ipynb `
+  --params examples/params/lang_radar.json `
+  --kernel rpymill `
+  --cell_tags "parameters,setup,graph_view,graph_output"
+```
+
 ## Processing Overview
 1. Load the notebook as JSON.
 2. Filter cells by specified tags (the `parameters` cell is always preserved).
@@ -90,6 +117,7 @@ This example demonstrates:
 For a detailed explanation in Japanese, see `README.jp.md`.
 
 ## Programmatic Usage (Experimental)
+
 RubyPyMill is primarily designed as a CLI tool.
 
 Internally, it exposes a Ruby execution API (`RubyPyMill::API`),
@@ -101,6 +129,27 @@ or future web APIs.
 The CLI is considered the stable interface.
 The Ruby API is experimental and may change.
 
+```ruby
+require "ruby_pymill"
+
+result = RubyPyMill::API.run(
+  input: "examples/notebooks/lang_radar.ipynb",
+  output: "examples/outputs/lang_radar_out.ipynb",
+  params: "examples/params/lang_radar.json",
+  kernel: "rpymill",
+  cell_tags: "parameters,setup,graph_output"
+)
+
+puts result.output
+```
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/inoue-0852/RubyPyMill-OSS/blob/main/CHANGELOG.md) for release history.
+
+
 ## License
 MIT License  
 Copyright (c) 2025 Hiroshi Inoue / OSS-Vision

data/lib/ruby_pymill/api.rb

@@ -1,59 +1,89 @@
 # lib/ruby_pymill/api.rb
-require "open3"
+require "fileutils"
 
 module RubyPyMill
+  class Error < StandardError; end
+  class ExecutionError < Error; end
+
+  Result = Struct.new(
+    :success,
+    :output,
+    :filtered_input,
+    :command,
+    :stdout,
+    :stderr,
+    keyword_init: true
+  ) do
+    def success?
+      success
+    end
+  end
+
   module API
-    # Ruby から notebook を実行する公式API
+    # Ruby から notebook を実行する公開API
     #
     # 例:
-    #   RubyPyMill::API.run(
-    #     notebook: "demo/notebooks/xxx.ipynb",
-    #     output:   "demo/outputs/out.ipynb",
-    #     kernel:   "rpymill",
-    #     cell_tags:"setup,preprocess,report",
-    #     params:   "demo/params/kodama.json",
-    #     log:      "demo/logs/run_xxx.log"
+    #   result = RubyPyMill::API.run(
+    #     input:     "examples/notebooks/lang_radar.ipynb",
+    #     output:    "examples/outputs/lang_radar_out.ipynb",
+    #     kernel:    "rpymill",
+    #     cell_tags: "parameters,setup,graph_output",
+    #     params:    "examples/params/lang_radar.json",
+    #     log:       "examples/logs/lang_radar.log"
+    #   )
+    #
+    #   puts result.output
+    #
+    # 後方互換: input: の旧名称 notebook: も引き続き使用可能
+    #   result = RubyPyMill::API.run(
+    #     notebook: "examples/notebooks/lang_radar.ipynb",
+    #     ...
     #   )
     #
     def self.run(
-      notebook:,
+      input: nil,
+      notebook: nil,
       output:,
       kernel: "rpymill",
       cell_tags: nil,
       params: nil,
-      log: nil
+      log: nil,
+      dry_run: false,
+      logger: $stdout,
+      cwd: nil
     )
-      cmd = [
-        "ruby_pymill", "exec",
-        notebook,
-        "--output", output,
-        "--kernel", kernel,
-      ]
-      cmd += ["--cell-tag", cell_tags] if cell_tags && !cell_tags.empty?
-      cmd += ["--params", params]      if params && !params.empty?
-
-      stdout_all = +""
-      status = nil
-
-      Open3.popen2e(*cmd) do |_stdin, stdout_err, wait_thr|
-        stdout_err.each do |line|
-          print line          # コンソールにも流す
-          stdout_all << line  # ログにも残す
-        end
-        status = wait_thr.value
-      end
+      # notebook: は input: の旧名称（後方互換）
+      # Add `notebook:` as a backward-compatible alias for `input:` in API.run
+      resolved_input = input || notebook
+      raise ArgumentError, "input: (or notebook:) is required" if resolved_input.nil?
+
+      runner = Runner.new(
+        kernel: kernel,
+        cwd: cwd,
+        logger: logger,
+        cell_tags: cell_tags
+      )
+
+      result = runner.run(
+        input_ipynb: resolved_input,
+        output_ipynb: output,
+        params_json: params,
+        kernel: kernel,
+        dry_run: dry_run,
+        cell_tags: cell_tags
+      )
 
       if log
         log_dir = File.dirname(log)
-        Dir.mkdir(log_dir) unless Dir.exist?(log_dir)
-        File.write(log, stdout_all)
+        FileUtils.mkdir_p(log_dir)
+        File.write(log, [result.stdout, result.stderr].reject(&:empty?).join)
       end
 
-      unless status&.success?
-        raise "ruby_pymill failed (status=#{status.exitstatus})"
+      unless result.success?
+        raise ExecutionError, "ruby_pymill failed"
       end
 
-      stdout_all
+      result
     end
   end
-end
+end

data/lib/ruby_pymill/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module RubyPyMill
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/ruby_pymill.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "ruby_pymill/version"
-require_relative "ruby_pymill/api"
 require "json"
 require "open3"
 require "tmpdir"
@@ -12,14 +11,14 @@ module RubyPyMill
       @kernel    = kernel
       @cwd       = cwd
       @logger    = logger
-      @cell_tags = normalize_tags(cell_tags)  # ← 文字列/配列どちらでもOKに
+      @cell_tags = normalize_tags(cell_tags)
     end
 
     # params_json: path to json file or JSON string
     # cell_tags  : initialize の指定を上書き可能（カンマ/空白区切り文字列 or 配列）
     def run(input_ipynb:, output_ipynb:, params_json: nil, kernel: nil, dry_run: false, cell_tags: nil)
       k    = kernel || @kernel
-      tags = normalize_tags(cell_tags.nil? ? @cell_tags : cell_tags)  # ← 正規化して複数タグ対応
+      tags = normalize_tags(cell_tags.nil? ? @cell_tags : cell_tags)
 
       # 1) タグ指定があればノートを事前フィルタ
       filtered_input = tags.empty? ? input_ipynb : filter_by_tags(input_ipynb, tags)
@@ -38,14 +37,32 @@ module RubyPyMill
         end
       end
 
-      cmd = args.join(" ")
-      @logger.puts "[RubyPyMill] #{dry_run ? 'DRY' : 'RUN'}: #{cmd}"
-      return true if dry_run
+      cmd_str = args.join(" ")
+      @logger.puts "[RubyPyMill] #{dry_run ? 'DRY' : 'RUN'}: #{cmd_str}"
 
-      stdout_str, stderr_str, status = Open3.capture3(cmd, chdir: @cwd || Dir.pwd)
+      if dry_run
+        return Result.new(
+          success: true,
+          output: output_ipynb,
+          filtered_input: filtered_input,
+          command: cmd_str,
+          stdout: "",
+          stderr: ""
+        )
+      end
+
+      stdout_str, stderr_str, status = Open3.capture3(*args, chdir: @cwd || Dir.pwd)
       @logger.puts stdout_str unless stdout_str.empty?
       @logger.puts stderr_str unless stderr_str.empty?
-      status.success?
+
+      Result.new(
+        success: status.success?,
+        output: output_ipynb,
+        filtered_input: filtered_input,
+        command: cmd_str,
+        stdout: stdout_str,
+        stderr: stderr_str
+      )
     end
 
     private
@@ -71,7 +88,9 @@ module RubyPyMill
 
       # 万一ゼロ件なら parameters 系のみ確保
       if kept.empty?
-        kept = cells.select { |c| (Array(c.dig("metadata", "tags")) & %w[parameters injected-parameters]).any? }
+        kept = cells.select do |c|
+          (Array(c.dig("metadata", "tags")) & %w[parameters injected-parameters]).any?
+        end
       end
 
       filtered = data.dup
@@ -84,3 +103,5 @@ module RubyPyMill
     end
   end
 end
+
+require_relative "ruby_pymill/api"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_pymill
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Hiroshi Inoue
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-10 00:00:00.000000000 Z
+date: 2026-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -38,10 +38,12 @@ files:
 - lib/ruby_pymill.rb
 - lib/ruby_pymill/api.rb
 - lib/ruby_pymill/version.rb
-homepage: https://github.com/inoue-0852/RubyPyMill
+homepage: https://github.com/inoue-0852/RubyPyMill-OSS
 licenses:
 - MIT
-metadata: {}
+metadata:
+  changelog_uri: https://github.com/inoue-0852/RubyPyMill-OSS/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/inoue-0852/RubyPyMill-OSS
 post_install_message:
 rdoc_options: []
 require_paths: