{"id":29709638,"url":"https://github.com/t3tra-dev/jvm-pybind","last_synced_at":"2025-07-23T20:06:41.213Z","repository":{"id":305396149,"uuid":"1022789285","full_name":"t3tra-dev/jvm-pybind","owner":"t3tra-dev","description":"JVM bindings for Python that enable seamless integration between Python and Java code through JNI (Java Native Interface).","archived":false,"fork":false,"pushed_at":"2025-07-19T22:49:50.000Z","size":120,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-19T22:53:04.864Z","etag":null,"topics":["java","jni","jvm","proxy","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t3tra-dev.png","metadata":{"files":{"readme":"README.ja.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T20:39:42.000Z","updated_at":"2025-07-19T22:49:53.000Z","dependencies_parsed_at":"2025-07-19T22:53:08.792Z","dependency_job_id":"9c52942a-e5dc-43c2-8ef6-a5d4a9c50e00","html_url":"https://github.com/t3tra-dev/jvm-pybind","commit_stats":null,"previous_names":["t3tra-dev/jvm-pybind"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/t3tra-dev/jvm-pybind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3tra-dev%2Fjvm-pybind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3tra-dev%2Fjvm-pybind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3tra-dev%2Fjvm-pybind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3tra-dev%2Fjvm-pybind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t3tra-dev","download_url":"https://codeload.github.com/t3tra-dev/jvm-pybind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t3tra-dev%2Fjvm-pybind/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266738945,"owners_count":23976490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","jni","jvm","proxy","python","python3"],"created_at":"2025-07-23T20:06:40.644Z","updated_at":"2025-07-23T20:06:41.203Z","avatar_url":"https://github.com/t3tra-dev.png","language":"Python","readme":"[[英語/English](README.md)]\n\n# JVM-PyBind\n\nJNI (Java Native Interface) を通じて Python と Java コードをシームレスに統合する JVM バインディングライブラリです。\n\n## 特徴\n\n- **直接的な JNI 統合**: ctypes を使用した低レベル JNI バインディングで最大限のパフォーマンスを実現\n- **動的クラス発見**: リフレクションを使用した Java クラス、メソッド、フィールドの自動発見\n- **Python インポートフック**: 標準的な Python の import 構文で Java クラスにアクセス可能\n- **型変換**: Python と Java 型の自動変換\n- **メモリ安全性**: 適切な JNI 参照管理と安全なシャットダウン手順\n- **クロスプラットフォーム**: Windows、macOS (ARM64 を含む)、Linux をサポート\n- **設定**: pyproject.toml による柔軟な設定\n\n## クイックスタート\n\n### インストール\n\n```bash\npip install jvm-pybind\n```\n\n### 基本的な使用方法\n\n```python\n# 標準的なPython構文でJavaクラスをインポート\nfrom java.lang import System\n\n# Javaメソッドを直接呼び出し\nSystem.out.println(\"Hello from JVM!\")\n\n# Javaプロパティにアクセス\nprint(f\"Java Version: {System.getProperty('java.version')}\")\nprint(f\"Java Vendor: {System.getProperty('java.vendor')}\")\n```\n\n## コマンドラインインターフェース\n\njvm-pybind は開発環境での Java 型スタブ管理のための CLI を提供します。\n\n### インストール\n\nIDE サポートと自動補完を有効にするために型スタブをインストール:\n\n```bash\n# 現在の仮想環境にJava型スタブをインストール\npython -m jvm --install-stub\n```\n\n### アンインストール\n\n不要になった型スタブを削除:\n\n```bash\n# 現在の仮想環境からJava型スタブを削除\npython -m jvm --uninstall-stub\n```\n\n### PTH ファイルインストール\n\n仮想環境で自動的に JVM インポートを有効にする .pth ファイルをインストール:\n\n```bash\n# 自動インポート用の jvm.pth ファイルをインストール\npython -m jvm --install-pth\n```\n\nこれにより、仮想環境の `site-packages` ディレクトリに `jvm.pth` ファイルが作成され、Python 起動時に自動的に JVM モジュールがインポートされ、手動初期化なしでシームレスに Java クラスをインポートできるようになります。\n\n### 機能\n\n**型スタブ管理:**\n\n- **スタブインストール**: 仮想環境を自動検出し、IDE 支援向けの Java 型スタブをインストール\n- **スタブアンインストール**: インストールされた全ての Java 型スタブをクリーンに削除\n- **自動生成**: 必要に応じて JVM インストールから新しいスタブを生成\n- **仮想環境検出**: venv、virtualenv、conda、その他の Python 環境マネージャーと連携\n\n**PTH ファイル管理:**\n\n- **PTH ファイルインストール**: Python 起動時に自動的に JVM モジュールをインポートする `jvm.pth` ファイルを仮想環境に作成\n- **自動インポート**: 手動の JVM 初期化なしでシームレスな Java クラスインポートを実現\n- **仮想環境安全性**: アクティブな仮想環境内でのみ動作し、分離されたセットアップを保証\n\n**サポートされるパッケージ:**\n\n- `java.lang` - Java コアクラス (String、System、Object 等)\n- `java.util` - コレクションとユーティリティ (List、Map、ArrayList 等)\n- `java.io` - 入出力クラス (File、InputStream、OutputStream 等)\n\n### 要件\n\n- **仮想環境**: CLI 操作にはアクティブな仮想環境が必要\n- **JVM インストール**: スタブ生成のために Java がインストールされ、アクセス可能である必要があります\n\n### 例\n\n```bash\n# 仮想環境の作成とアクティベート\npython -m venv .venv\nsource .venv/bin/activate  # Windows: .venv\\Scripts\\activate\n\n# jvm-pybindのインストール\npip install jvm\n\n# IDEサポート用の型スタブをインストール\npython -m jvm --install-stub\n\n# または自動JVMインポート用のPTHファイルをインストール\npython -m jvm --install-pth\n\n# IDEで自動補完が利用可能になります\nfrom java.lang import System  # IDEが利用可能なメソッドを表示\n```\n\n### ヘルプ\n\n```bash\npython -m jvm --help\n```\n\n出力:\n\n```\nusage: jvm [-h] (--install-stub | --uninstall-stub | --install-pth)\n\nJVM-PyBind: Python bindings for JVM with type stub management\n\noptions:\n  -h, --help         show this help message and exit\n  --install-stub     Install JDK type stubs to the current virtual environment\n  --uninstall-stub   Remove JDK type stubs from the current virtual environment\n  --install-pth      Install jvm.pth file to enable automatic JVM import in\n                     virtual environment\n\nExamples:\n  python -m jvm --install-stub     Install JDK type stubs to virtual environment\n  python -m jvm --uninstall-stub   Remove JDK type stubs from virtual environment\n  python -m jvm --install-pth      Install jvm.pth file to enable automatic JVM import\n```\n\n### カスタム Java クラスの使用 (実験的機能)\n\n\u003e ⚠️ **注意**: カスタム Java クラスへのアクセスは現在実験的な機能です。JVM 起動時に JAR ファイルをクラスパスに含めることはできますが、Python の import 構文を使った直接的なカスタムクラスへのアクセスはまだ完全に実装されていません。\n\n**現在利用可能な機能:**\n\n```toml\n# pyproject.toml - JARファイルはJVMクラスパスに読み込まれます\n[tool.jvm]\njava-version = \"17\"\nclasspath = [\"hello.jar\"]\n```\n\n**計画中の機能 (まだ利用できません) :**\n\n```python\n# 将来のバージョンでサポート予定\nfrom mypkg import Hello  # まだ実装されていません\nmessage = Hello.greet(\"World\")\n```\n\n**現在の回避方法:**\n内部 API を使用してカスタムクラスにアクセス:\n\n```python\nimport jvm\n\n# JVMインスタンスを取得\njvm_instance = jvm.JVM.get_instance()\n\n# カスタムクラスを検索\nhello_class = jvm_instance.find_class(\"mypkg/Hello\")\n\n# 低レベルAPIを通じてメソッドにアクセス\n#  (詳細は以下の内部APIセクションを参照)\n```\n\n## 設定\n\n`pyproject.toml`ファイルで jvm-pybind を設定します:\n\n```toml\n[tool.jvm]\njava-version = \"17\"  # 使用するJavaバージョン\nclasspath = [        # 含めるJARファイルとディレクトリ\n    \"path/to/your.jar\",\n    \"path/to/classes/\"\n]\n\n[tool.jvm.deps]\nmaven = [            # Maven依存関係 (将来の機能)\n    \"org.apache.commons:commons-lang3:3.12.0\"\n]\n```\n\n## システム要件\n\n### Java 実行環境\n\n- **Java 17** (推奨、設定可能)\n- サポートされる JDK ディストリビューション:\n  - Oracle JDK\n  - Eclipse Adoptium (旧 AdoptOpenJDK)\n  - Amazon Corretto\n  - Microsoft Build of OpenJDK\n  - Azul Zulu\n  - OpenJDK\n\n### Python\n\n- **Python 3.12+**\n- サポートされるプラットフォーム:\n  - Windows (x64)\n  - macOS (Intel および Apple Silicon)\n  - Linux (x64、ARM64)\n\n## アーキテクチャ\n\njvm-pybind は以下の主要コンポーネントで構成されています:\n\n- **JVMLoader**: JVM の初期化と libjvm ライブラリの読み込み\n- **JNIHelper**: 型安全性を備えた低レベル JNI 関数バインディング\n- **JVM**: Java クラス発見とメソッド実行のメインインターフェース\n- **プロキシクラス**: Java パッケージ、クラス、オブジェクトの Python ラッパー\n- **インポートフック**: Python のインポートシステムとの統合\n\n## 高度な使用方法\n\n### 直接的な JNI アクセス\n\n```python\nimport jvm\n\n# JVMインスタンスを取得\njvm_instance = jvm.get_jvm()\n\n# Javaクラスを検索\nstring_class = jvm_instance.find_class(\"java.lang.String\")\n\n# クラス情報にアクセス\nprint(f\"メソッド数: {len(string_class.methods)}\")\nprint(f\"フィールド数: {len(string_class.fields)}\")\n```\n\n### メモリ管理\n\nライブラリは自動的に JNI 参照を管理しますが、明示的にメモリを制御することも可能です:\n\n```python\nfrom java.lang import System\n\n# JVMはPython終了時に自動的にシャットダウンされます\n# 明示的な制御の場合:\njvm.shutdown()\n```\n\n## 内部 API リファレンス\n\n\u003e 📋 **注意**: このセクションは上級ユーザーと開発者向けの内部 API について説明します。ほとんどの用途では、高レベルな import 構文 (`from java.lang import System`) の使用を推奨します。\n\n### JVM インスタンス管理\n\n```python\nimport jvm\n\n# 現在のJVMインスタンスを取得 (実行中の場合)\njvm_instance = jvm.get_jvm()  # JVMが開始されていない場合はNoneを返す\n\n# カスタム設定でJVMを開始\nfrom jvm.config import Config\nfrom jvm.loader import JVMLoader\n\nconfig = Config(java_version=\"17\", classpath=[\"path/to/jar\"], deps={})\njvm_instance = JVMLoader(config).start()\n```\n\n### 低レベルクラスアクセス\n\n```python\n# 名前でJavaクラスを検索\njava_class = jvm_instance.find_class(\"java/lang/String\")\nprint(f\"クラス: {java_class.name}\")\nprint(f\"メソッド数: {len(java_class.methods)}\")\nprint(f\"フィールド数: {len(java_class.fields)}\")\n\n# クラスのメソッドとフィールドにアクセス\nfor method in java_class.methods:\n    print(f\"メソッド: {method.name}({', '.join(method.parameters)}) -\u003e {method.return_type}\")\n    print(f\"静的: {method.is_static}\")\n```\n\n### 直接的な JNI 操作\n\n```python\n# 基盤となるJNIヘルパーにアクセス\njni = jvm_instance.jni\n\n# クラスを検索してメソッドIDを取得\nstring_class = jni.FindClass(\"java/lang/String\")\nlength_method = jni.GetMethodID(string_class, \"length\", \"()I\")\n\n# Java文字列を作成\njava_str = jni.NewStringUTF(\"Hello World\")\n\n# メソッドを呼び出し\nlength = jni.CallIntMethod(java_str, length_method)\nprint(f\"文字列の長さ: {length}\")\n```\n\n### パッケージ発見\n\n```python\n# パッケージ内のクラスを発見\nclasses = jvm_instance.discover_package_classes(\"java.util\")\nfor class_name in classes:\n    print(f\"クラスを発見: {class_name}\")\n```\n\n### プロキシオブジェクト\n\n```python\nfrom jvm.proxy import ClassProxy, PackageProxy\n\n# Javaパッケージのプロキシを作成\njava_lang = PackageProxy(jvm_instance, \"java.lang\")\nsystem_class = java_lang.System  # ClassProxyを返す\n\n# 静的メソッドにアクセス\nsystem_class.gc()  # System.gc()を呼び出し\nproperty_value = system_class.getProperty(\"java.version\")\n```\n\n### 設定アクセス\n\n```python\nfrom jvm.config import Config\n\n# pyproject.tomlから設定を読み込み\nconfig = Config.from_pyproject()\nprint(f\"Javaバージョン: {config.java_version}\")\nprint(f\"クラスパス: {config.classpath}\")\nprint(f\"依存関係: {config.deps}\")\n\n# カスタム設定を作成\ncustom_config = Config(\n    java_version=\"11\",\n    classpath=[\"/path/to/custom.jar\"],\n    deps={\"maven\": [\"org.apache.commons:commons-lang3:3.12.0\"]}\n)\n```\n\n### 型変換\n\n```python\nfrom jvm.typeconv import to_java, to_python\n\n# Python値をJavaに変換\njava_string = to_java(jvm_instance, \"Hello\")\njava_int = to_java(jvm_instance, 42)\njava_bool = to_java(jvm_instance, True)\n\n# Java値をPythonに変換\npython_value = to_python(jvm_instance, java_string)\n```\n\n### 例外処理\n\n```python\nfrom jvm.jvm import JNIException\n\ntry:\n    # 失敗する可能性のあるJNI操作\n    unknown_class = jvm_instance.find_class(\"com/nonexistent/Class\")\nexcept JNIException as e:\n    print(f\"JNIエラー: {e}\")\n```\n\n### 利用可能なクラスとメソッド\n\nインポートして使用できる主要なクラス:\n\n| クラス          | 目的                        | 使用例                          |\n| --------------- | --------------------------- | ------------------------------- |\n| `jvm.JVM`       | メイン JVM インターフェース | `jvm_instance.find_class()`     |\n| `jvm.JNIHelper` | 低レベル JNI 関数           | `jni.FindClass()`               |\n| `jvm.Config`    | 設定管理                    | `Config.from_pyproject()`       |\n| `jvm.JVMLoader` | JVM 初期化                  | `JVMLoader(config).start()`     |\n| `jvm.proxy.*`   | Java オブジェクトプロキシ   | `ClassProxy()`, `ObjectProxy()` |\n\n## 開発\n\n### 開発環境の設定\n\n```bash\n# リポジトリをクローン\ngit clone https://github.com/t3tra-dev/jvm-pybind.git\ncd jvm-pybind\n\n# 環境の初期化\n./reinstall.sh  # または手動で仮想環境を作成\n```\n\n### テストの実行\n\n```bash\n# サンプルを実行\ncd examples/hello\npython main.py\n```\n\n### プロジェクト構造\n\n```\njvm-pybind/\n├── src/jvm/           # メインパッケージ\n│   ├── __init__.py    # パッケージ初期化\n│   ├── jvm.py         # JVMインターフェース\n│   ├── jni.py         # JNIバインディング\n│   ├── loader.py      # JVMローダー\n│   ├── proxy.py       # Javaオブジェクトプロキシ\n│   ├── config.py      # 設定管理\n│   ├── typeconv.py    # 型変換ユーティリティ\n│   └── import_hook/   # Pythonインポートフック\n├── examples/          # 使用例\n└── tests/             # テストスイート\n```\n\n## サポートされる Java 型\n\n### プリミティブ型\n\n- `boolean` ↔ `bool`\n- `int` ↔ `int`\n- `long` ↔ `int`\n- `float` ↔ `float`\n- `double` ↔ `float`\n- `String` ↔ `str`\n\n### 複合型\n\n- Java オブジェクトはプロキシクラスでラップ\n- 配列とコレクション (計画中)\n- リフレクションによるカスタムクラス\n\n## パフォーマンス考慮事項\n\n- **JVM 起動**: 最初の Java インポート時に JVM が遅延初期化されます\n- **メモリ使用量**: JNI 参照は自動的に管理されます\n- **メソッド呼び出し**: 最適なパフォーマンスのための直接 JNI 呼び出し\n- **ARM64 最適化**: Apple Silicon 向けの特別な最適化\n\n## トラブルシューティング\n\n### よくある問題\n\n1. **Java が見つからない**: Java がインストールされ、`JAVA_HOME`が設定されていることを確認\n2. **ClassNotFoundException**: クラスパス設定を確認\n3. **メモリエラー**: アプリケーションに十分なヒープ空間があることを確認\n\n### デバッグモード\n\nデバッグログを有効にする:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\nfrom java.lang import System  # デバッグ出力を表示\n```\n\n## コントリビューション\n\nコントリビューションを歓迎します！プルリクエストをお気軽に提出してください。\n\n1. リポジトリをフォーク\n2. フィーチャーブランチを作成 (`git checkout -b feature/amazing-feature`)\n3. 変更をコミット (`git commit -m 'Add some amazing feature'`)\n4. ブランチにプッシュ (`git push origin feature/amazing-feature`)\n5. プルリクエストを開く\n\n## ライセンス\n\nこのプロジェクトは MIT ライセンスの下でライセンスされています - 詳細は[LICENSE](LICENSE)ファイルをご覧ください。\n\n## 謝辞\n\n- JNI 統合に Python の ctypes を使用して構築\n- JPype および類似の Java-Python ブリッジプロジェクトからインスピレーション\n- Python と Java コミュニティに特別な感謝\n\n## ロードマップ\n\n### 高優先度\n\n- [ ] **カスタム Java クラスのインポートサポート** - カスタムクラスに対する`from mypkg import MyClass`構文の実現\n- [ ] **強化された型変換** - より多くの Java 型 (配列、コレクション等) のサポート\n- [ ] **包括的なテストスイート** - 全機能の完全なテストカバレッジ\n\n### 中優先度\n\n- [ ] **Maven 依存関係解決** - Maven 依存関係の自動ダウンロードと管理\n- [ ] **Java コレクションサポート** - Java List、Map 等とのネイティブな Python 統合\n- [ ] **パフォーマンス最適化** - メソッド呼び出しの最適化とキャッシュ\n\n### 低優先度\n\n- [ ] **コールバックサポート** - Java コードから Python 関数の呼び出しを可能に\n- [ ] **高度なデバッグツール** - より良いエラーメッセージとデバッグ機能\n- [ ] **IDE 統合** - Java クラスの型ヒントと自動補完\n\n## 技術詳細\n\n### JNI 統合の仕組み\n\nこのライブラリは、ctypes を使用して JNI (Java Native Interface) と直接通信します。以下の手順で動作します:\n\n1. **JVM 初期化**: `JNI_CreateJavaVM`を呼び出して JVM を起動\n2. **クラス発見**: Java リフレクションを使用してクラス情報を取得\n3. **メソッド呼び出し**: JNI 関数を通じて Java メソッドを呼び出し\n4. **型変換**: Python と Java 間での自動型変換\n5. **メモリ管理**: JNI ローカル・グローバル参照の適切な管理\n\n### 安全性とパフォーマンス\n\n- **メモリリーク防止**: すべての JNI 参照を適切に管理\n- **例外処理**: Java の例外を Python の例外に変換\n- **スレッドセーフティ**: マルチスレッド環境での安全な動作\n- **ARM64 最適化**: Apple Silicon Mac での特別な最適化\n\n### 設定オプション\n\n`pyproject.toml`で以下の設定が可能です:\n\n```toml\n[tool.jvm]\n# Java バージョン (デフォルト: \"17\")\njava-version = \"11\"\n\n# クラスパス (JARファイルやディレクトリのリスト)\nclasspath = [\n    \"lib/my-library.jar\",\n    \"build/classes/\",\n    \"/absolute/path/to/classes/\"\n]\n\n# 将来的な機能: Maven依存関係\n[tool.jvm.deps]\nmaven = [\n    \"org.apache.commons:commons-lang3:3.12.0\",\n    \"com.google.guava:guava:31.1-jre\"\n]\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft3tra-dev%2Fjvm-pybind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft3tra-dev%2Fjvm-pybind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft3tra-dev%2Fjvm-pybind/lists"}