sing-box-python 1.13.18__cp313-cp313-win_amd64.whl

sing_box_python-1.13.18.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: sing-box-python
+Version: 1.13.18
+Summary: Python binding for sing-box
+License: GPL-3.0-or-later
+Project-URL: Source, https://github.com/LorenEteval/sing-box-python
+Project-URL: sing-box, https://github.com/SagerNet/sing-box
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: Internet :: Proxy Servers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# sing-box-python
+
+[![Build and publish Python distributions](https://github.com/LorenEteval/sing-box-python/actions/workflows/build-and-publish.yml/badge.svg?branch=main)](https://github.com/LorenEteval/sing-box-python/actions/workflows/build-and-publish.yml)
+
+Python bindings for [sing-box](https://github.com/SagerNet/sing-box).
+
+## Install
+
+Prebuilt binary wheels include the native Go and C++ binding, so a supported installation does not require Go, CMake,
+or a C++ compiler.
+
+```
+pip install sing-box-python
+```
+
+Binary wheels are published for Linux x86-64 and ARM64, Windows x86-64 and ARM64, and macOS Intel and Apple Silicon.
+
+### Build from Source
+
+A source distribution is also published as a fallback. If pip cannot find a compatible wheel, it may build the native
+binding from source. A source build requires:
+
+* [Go 1.24.7](https://go.dev/doc/install) in `PATH`.
+* A working C and C++ compiler toolchain.
+* MinGW-w64 on Windows x86-64, or LLVM-MinGW on Windows ARM64, with `gcc` and `g++` available in `PATH`.
+
+The isolated Python build environment installs CMake, pybind11, setuptools, and wheel automatically. To build directly
+from a repository checkout:
+
+```
+pip install .
+```
+
+The build downloads sing-box's checksum-pinned, platform-specific Cronet Go module automatically. Wheels contain an
+isolated Cronet runtime (`libcronet.dylib`, `libcronet.so`, or `libcronet.dll`), loaded from an absolute package path
+during import. On macOS the build converts the pinned static archive into a separate dynamic library so Chromium's
+private C++ runtime cannot conflict with pybind11.
+
+## API
+
+```pycon
+>>> import singbox
+>>> help(singbox)
+Help on package singbox:
+
+NAME
+    singbox - Native Python bindings for starting and managing sing-box.
+
+PACKAGE CONTENTS
+    _native
+
+CLASSES
+    builtins.RuntimeError(builtins.Exception)
+        singbox._native.SingBoxError
+    pybind11_builtins.pybind11_object(builtins.object)
+        singbox._native.SingBox
+
+    class SingBox(pybind11_builtins.pybind11_object)
+     |  An explicitly managed, non-blocking in-process sing-box instance.
+     |
+     |  Unlike the module-level startFromJSON function, this class reports startup
+     |  errors as Python exceptions and does not wait for operating-system signals.
+     |  Call stop explicitly or use the instance as a context manager.
+     |
+     |  Methods defined here:
+     |
+     |  __enter__(...)
+     |      __enter__(self: singbox._native.SingBox) -> singbox._native.SingBox
+     |
+     |      Return this instance for use as a context manager.
+     |
+     |  __exit__(...)
+     |      __exit__(self: singbox._native.SingBox, arg0: object, arg1: object, arg2: object) -> None
+     |
+     |      Stop the instance when leaving a context-manager block.
+     |
+     |  __init__(...)
+     |      __init__(self: singbox._native.SingBox) -> None
+     |
+     |      Create a stopped sing-box instance.
+     |
+     |  queryStats(...)
+     |      queryStats(self: singbox._native.SingBox, patterns: collections.abc.Sequence[str] = [], reset: bool = False, regexp: bool = False) -> dict
+     |
+     |      Return available runtime, Clash, and V2Ray statistics as a dictionary.
+     |
+     |      patterns filters V2Ray counters. reset clears matched V2Ray counters after
+     |      reading, and regexp interprets patterns as regular expressions. Clash and
+     |      V2Ray sections are None when their corresponding sing-box services are not
+     |      enabled by the configuration. Runtime memory counters are always present.
+     |
+     |  startFromJSON(...)
+     |      startFromJSON(self: singbox._native.SingBox, json: str) -> None
+     |
+     |      Start this instance from a UTF-8 JSON configuration string.
+     |
+     |      The call returns after the service starts. Invalid configuration, construction,
+     |      or startup errors raise SingBoxError. Starting an already-running instance
+     |      raises RuntimeError.
+     |
+     |  stop(...)
+     |      stop(self: singbox._native.SingBox) -> None
+     |
+     |      Stop the instance and release its native resources; repeated calls are safe.
+     |
+     |  Readonly properties defined here:
+     |
+     |  handle
+     |      Opaque numeric instance identifier, or 0 while stopped.
+     |
+     |  running
+     |      Whether this instance currently owns a running native service.
+
+    class SingBoxError(builtins.RuntimeError)
+     |  An error reported by the managed sing-box native lifecycle API.
+
+FUNCTIONS
+    startFromJSON(...) method of pybind11_builtins.pybind11_detail_function_record instance
+        startFromJSON(json: str) -> None
+
+        Start sing-box from JSON and block until SIGINT or SIGTERM is received.
+
+        This process-oriented entry point is intended to be the target of a
+        multiprocessing.Process. Configuration decoding or construction failures exit
+        the process with status 23. Service startup failures call os.Exit(-1), whose
+        observed status is platform-dependent. Use SingBox for exception-based,
+        non-blocking in-process lifecycle management.
+
+DATA
+    __all__ = ['SingBox', 'SingBoxError', '__version__', 'startFromJSON']
+
+VERSION
+    v1.13.18
+```
+
+## Source Code Modification
+
+This repository, including the package that distributes to pypi,
+contains [sing-box](https://github.com/SagerNet/sing-box) source code and the additional binding code required to build
+the Python extension and its API.
+
+To make installation of this package easier, the original [sing-box](https://github.com/SagerNet/sing-box) source code
+is embedded instead of being added as a submodule. The official source files are unchanged. The binding is implemented
+by the added `singbox-go/binding` package and the C++/Python packaging files in this repository. To track the difference,
+compare `singbox-go` with the upstream commit while excluding the added `binding` directory.
+
+## Binary Wheel Platforms
+
+The distributions are built and tested in [GitHub Actions](https://github.com/LorenEteval/sing-box-python/actions).
+
+| Platform | Architecture | CPython |
+|----------|--------------|---------|
+| Linux | x86-64 | 3.8-3.14, 3.13t, 3.14t |
+| Linux | ARM64 | 3.8-3.14, 3.13t, 3.14t |
+| Windows | x86-64 | 3.8-3.14, 3.13t, 3.14t |
+| Windows | ARM64 | 3.9-3.14, 3.13t, 3.14t |
+| macOS | Intel | 3.8-3.14, 3.13t, 3.14t |
+| macOS | Apple Silicon | 3.8-3.14, 3.13t, 3.14t |
+
+Naive outbound is included on all wheel platforms in the table. Cronet is bundled as an isolated shared runtime on
+macOS, Linux, and Windows. The macOS runtime is produced from the pinned static archive during the wheel build. The
+Cronet artifact comes from the platform module and exact version already pinned by sing-box v1.13.18's `go.mod` and
+verified by `go.sum`; the workflow does not build an unrelated Cronet revision.
+Custom source builds can override the complete sing-box tag list with the `SINGBOX_BUILD_TAGS` environment variable.
+
+## License
+
+The license for this project follows its original Go repository [sing-box](https://github.com/SagerNet/sing-box)
+and is under [GNU GPL v3 or later](https://github.com/LorenEteval/sing-box-python/blob/main/LICENSE).

sing_box_python-1.13.18.dist-info/RECORD

@@ -0,0 +1,10 @@
+sing_box_python-1.13.18.dist-info/licenses/LICENSE,sha256=uzgFhitYOu5zrW94BexjR0ejclemN6MGmFeEPwXqWJw,808
+singbox/__init__.py,sha256=3Ov17SdLJ6wU_MCYiHPXKao-Ynt1w32a6OyT6NR4Umg,911
+singbox/_native.cp313-win_amd64.pyd,sha256=JaLcLXIMm92Ufx9zcJCdbb6TdAN5RBiCy9dq83tIiFU,60217344
+singbox/_native.pyi,sha256=T9u_5p7QRJVEMiymiHM03HrLF40ruRGYQVUn7WszaJc,672
+singbox/libcronet.dll,sha256=JX-WYRn_ypHXos4RCktmi4ZdiL8u1TOf0GpWRLDQKCM,9528832
+singbox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sing_box_python-1.13.18.dist-info/METADATA,sha256=vABrunCVtJt3KeH_LMnRxVrPXncmi24oU10gGFS7quM,8248
+sing_box_python-1.13.18.dist-info/WHEEL,sha256=0LUNoHxLvcpw9db_x0XozE5jW73-_GOAO7fDDJ4Xt4Q,101
+sing_box_python-1.13.18.dist-info/top_level.txt,sha256=Fnr72E7XDvIS6X0EVgT-uPHy38L9LthQv3vakhSOiXo,8
+sing_box_python-1.13.18.dist-info/RECORD,,

sing_box_python-1.13.18.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64
+

sing_box_python-1.13.18.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+Copyright (C) 2022 by nekohasekai <contact-sagernet@sekai.icu>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+In addition, no derivative work may use the name or imply association
+with this application without prior consent.

sing_box_python-1.13.18.dist-info/top_level.txt

@@ -0,0 +1 @@
+singbox

singbox/__init__.py

@@ -0,0 +1,31 @@
+"""Native Python bindings for starting and managing sing-box."""
+
+from pathlib import Path as _Path
+
+from . import _native as _native
+
+if hasattr(_native, "_loadCronetLibrary"):
+    _cronet_candidates = (
+        _Path(__file__).with_name("libcronet.dll"),
+        _Path(__file__).with_name("libcronet.dylib"),
+        _Path(__file__).with_name("libcronet.so"),
+    )
+    _cronet_path = next(
+        (candidate for candidate in _cronet_candidates if candidate.is_file()),
+        None,
+    )
+    if _cronet_path is None:
+        raise ImportError("the wheel-bundled Cronet runtime is missing")
+    _native._loadCronetLibrary(str(_cronet_path.resolve()))
+
+SingBox = _native.SingBox
+SingBoxError = _native.SingBoxError
+__version__ = _native.__version__
+startFromJSON = _native.startFromJSON
+
+__all__ = [
+    "SingBox",
+    "SingBoxError",
+    "__version__",
+    "startFromJSON",
+]

singbox/_native.pyi

@@ -0,0 +1,24 @@
+from typing import Any, Sequence
+
+class SingBoxError(RuntimeError): ...
+
+class SingBox:
+    def __init__(self) -> None: ...
+    def startFromJSON(self, json: str) -> None: ...
+    def stop(self) -> None: ...
+    def queryStats(
+        self,
+        patterns: Sequence[str] = ...,
+        reset: bool = ...,
+        regexp: bool = ...,
+    ) -> dict[str, Any]: ...
+    @property
+    def running(self) -> bool: ...
+    @property
+    def handle(self) -> int: ...
+    def __enter__(self) -> SingBox: ...
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None: ...
+
+def startFromJSON(json: str) -> None: ...
+
+__version__: str