cube-python 0.4.0__cp312-cp312-macosx_10_15_x86_64.whl

cube_python-0.4.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: cube-python
+Version: 0.4.0
+Summary: Python binding for Cube C++ library
+Author-email: coshz <fsinhx@gmail.com>
+License: MIT
+Project-URL: Documentation, https://github.com/coshz/cube/tree/master/bindings/python#readme
+Project-URL: Source, https://github.com/coshz/cube
+Project-URL: Bug Tracker, https://github.com/coshz/cube/issues
+Keywords: game,rubiks-cube,bindings
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cube-python
+
+[![PyPI version](https://img.shields.io/pypi/v/cube-python.svg)](https://pypi.org/project/cube-python/)
+[![License](https://img.shields.io/github/license/yourusername/cube)](https://github.com/yourusername/cube/blob/main/LICENSE)
+[![GitHub](https://img.shields.io/badge/github-coshz%2Fcube-blue?logo=github)](https://github.com/coshz/cube/tree/master/bindings/python)
+
+
+High-performance Rubik's Cube solver Python bindings powered by C/C++ FFI.
+
+---
+
+## Installation
+
+```bash
+pip install cube-python
+```
+
+## Quickstart
+
+```python
+iimport pycube
+from pycube import SolveError
+
+# Default solved cube string representation
+print(f"Target State: {pycube.CUBE_ID}")
+
+# Validate state solvability
+scrambled = pycube.facecube("U F U' L2 R L' D2 B")
+
+if pycube.solvable(scrambled):
+    try:
+        # Find solution sequence
+        solution = pycube.solve(scrambled, step=30, best=True)
+        print(f"Solution: {solution}")
+
+        # Apply solution to verify end state
+        end_state = pycube.facecube(solution, scrambled)
+        assert end_state == pycube.CUBE_ID
+
+    except SolveError as e:
+        print(f"Failed to solve cube: {e}")
+```
+
+## 📖 API Reference
+
+```python
+import pycube
+from pycube import SolveError, CUBE_ID
+```
+
+### Functions
+
+| Function | Description |
+| :--- | :--- |
+| `solve(src, tgt=CUBE_ID, step=30, best=False)` | Solves the cube state string `src`. Returns solution string or raises `SolveError`. |
+| `facecube(maneuver, cube=CUBE_ID)` | Applies move sequence (e.g., `"U F U' L2"`) to a cube state and returns the new state. |
+| `solvable(cube)` | Returns `True` if the 54-character state string is physically solvable. |
+| `permutation(ms, fmt=2)` | Returns a permutation representation for a move sequence or state. |
+
+### Constants & Exceptions
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `CUBE_ID` | `str` | Constant representing the standard solved state (`"UUUUUUUUURRRRRRRRRFFFFFFFFFDDDDDDDDDLLLLLLLLLBBBBBBBBB"`). |
+| `SolveError` | `Exception` | Raised when the state is invalid, unsolvable, or exceeds search step limits. |
+
+## 📄 License
+
+[MIT](LICENSE) © coshz

cube_python-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cube_python-0.4.0.dist-info/licenses/LICENSE,sha256=5aug9F9MisxQd1Gd8T_2O8BQRvO-FdDVxmZxVkjA4AM,1049
+pycube/__init__.py,sha256=SQNdI3oSZL3MRqesA71OX8V9u16B8XTWEgSSWAmVIDY,1665
+pycube/_exceptions.py,sha256=k_3G4Abh6Q8mWfctG19d0M3eWcHZ9JMxB6hfTHq6awo,430
+pycube/_ffi.py,sha256=TocmwoSwKBvSwmWg2pYzYnRe3bXhJr5JdlVAh8v7_AA,1484
+pycube/_native.cpython-312-darwin.so,sha256=LF7RfZNqYcEAImkLaaCAIbKlHCudUM-IvRDBMQUl45g,267224
+cube_python-0.4.0.dist-info/METADATA,sha256=VfBnTEfBRA-M1T4N4xaHUdgMEit1V4uiOH0UrjQIUvw,2847
+cube_python-0.4.0.dist-info/WHEEL,sha256=2rZ8eqxxuiDxbYnSQc_T1EfLxym8FKbM652VP35vVF4,111
+cube_python-0.4.0.dist-info/top_level.txt,sha256=ioKlXjCw0-J53WSFSUPfhI-3sU1IbOVH2rR8nFl6FMc,7
+cube_python-0.4.0.dist-info/RECORD,,

cube_python-0.4.0.dist-info/WHEEL

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

cube_python-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 coshz
+
+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.

cube_python-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pycube

pycube/__init__.py

@@ -0,0 +1,51 @@
+from ._ffi import _libcube as lib
+from ._exceptions import SolveResult, SolveError
+import ctypes 
+
+__all__ = [ 'solve', 'facecube', 'permutation', 'solvable', 'CUBE_ID' ]
+
+CUBE_ID = lib.CUBE_ID
+
+def solve(src: str, tgt: str = CUBE_ID, step: int = 30, best: bool = False) -> str:
+    """ Solve the cube.
+
+    Args:
+        src     : the source color configuration;
+        tgt     : the target color configuration; (None => cid)
+        step    : the maximum allowed steps;
+        best    : find the shorter (but slower) solution
+    
+    Return:
+        the sequence of moves
+    
+    Raise:
+        SolveError(code) if the src/tgt cube configuration is invalid or 
+        the cube is unsolvable or no solution found within the step limit.
+    """
+    src_bytes = src.encode('utf-8')
+    tgt_bytes = tgt.encode('utf-8')
+    buffer = ctypes.create_string_buffer(lib.CUBE_BS)
+    code = lib.solve(buffer,src_bytes,tgt_bytes,step,best)
+    if code != SolveResult.SUCCESS: 
+        raise SolveError(code)
+    return buffer.value.decode('utf-8')
+
+
+def facecube(manuuver: str, cube: str = CUBE_ID) -> str: 
+    maneuver_bytes = manuuver.encode('utf-8')
+    cube_bytes = cube.encode('utf-8')
+    buffer = ctypes.create_string_buffer(lib.CUBE_BS)
+    lib.facecube(buffer,maneuver_bytes,cube_bytes)
+    return buffer.value.decode('utf-8')
+
+
+def permutation(ms_or_cube: str, fmt: int = 2) -> str: 
+    mc = ms_or_cube.encode('utf-8')
+    buffer = ctypes.create_string_buffer(lib.CUBE_BS)
+    lib.permutation(buffer,mc,fmt)
+    return buffer.value.decode('utf-8')
+
+
+def solvable(cube: str) -> bool: 
+    cube_bytes = cube.encode('utf-8')
+    return lib.solvable(cube_bytes)

pycube/_exceptions.py

@@ -0,0 +1,20 @@
+from enum import IntEnum
+from ._ffi import _libcube as lib
+
+__all__ = ['SolveResult', 'SolveError']
+
+
+class SolveResult(IntEnum):
+    SUCCESS = 0
+    UNSOLVABLE = 1
+    NOT_FOUND = 2
+    INVALID_SRC = 3
+    INVALID_TGT = 4
+    UNKNOWN_ERR = 5
+
+
+class SolveError(Exception):
+    def __init__(self, sr: SolveResult):
+        self.value = sr
+        msg = lib.solve_result_to_string(sr)
+        super().__init__(f"[{sr.name}] {msg}")

pycube/_ffi.py

@@ -0,0 +1,53 @@
+"""
+Python ctypes wrapper and FFI definitions for the C++ shared library.
+
+Ref: 
+    ../cxx_src/cube.h
+    
+See Also:
+    ../cxx_src/cube_amalg.min.cpp
+"""
+
+from ctypes import CDLL, c_char_p, c_int32, c_bool
+from pathlib import Path
+
+class CubeCDLL(CDLL):
+    CUBE_BS = 128
+    CUBE_ID = "UUUUUUUUURRRRRRRRRFFFFFFFFFDDDDDDDDDLLLLLLLLLBBBBBBBBB"
+
+
+def _load_library() -> CubeCDLL:
+    package_dir = Path(__file__).parent 
+    allowed_suffixes = { '.so', '.dylib', '.dll', '.pyd' }
+    candidates = [ 
+        p for p in package_dir.glob("_native*")
+        if p.suffix in allowed_suffixes
+    ]
+
+    if not candidates: 
+        raise FileNotFoundError(
+            f"Could not find compiled C++ shared library inside '{package_dir}'.\n"
+            "If you are developing locally, run `pip install -e .` or "
+            "`python setup.py build_ext --inplace` to build the native extension first."
+        )
+        
+    lib_path = str(candidates[0])
+    return CubeCDLL(lib_path)
+
+
+_libcube = _load_library() 
+
+_libcube.solve.argtypes = [c_char_p, c_char_p,  c_char_p, c_int32, c_bool]
+_libcube.solve.restype = c_int32
+
+_libcube.facecube.argtypes = [c_char_p, c_char_p, c_char_p]
+_libcube.facecube.restype = None
+
+_libcube.solvable.argtypes = [c_char_p]
+_libcube.solvable.restype = c_bool
+
+_libcube.permutation.argtypes = [c_char_p, c_char_p]
+_libcube.permutation.restype = None
+
+_libcube.solve_result_to_string.argtypes = [c_int32]
+_libcube.solve_result_to_string.restype = c_char_p