magiccube

library1.2.0pypypi✓ verified 85d ago

MagicCube is a Python library providing an NxNxN Rubik's Cube implementation. It allows for cube manipulation, scrambling, and solving (including Kociemba's algorithm). The current stable version is 1.2.0, with ongoing development reflected in beta releases, though stable releases are less frequent.

ai-ml

pip install magiccube

github ↗package ↗

INSTALL

IMPORT

SIG · MAGICCUBE

magiccube

ai-mlpythonv1.2.0

Install

3.6s avg

Import

277ms

Disk

89MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.274s · 89.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.6s · import 0.280s · 86MB

89MB installed

● package 89MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Cube

✓ from magiccube import Cube

✗ from magiccube.cube import Cube

As of v1.2.0, key public objects like `Cube` are directly exposed in the top-level `magiccube` namespace. Direct import is preferred.

Move

✓ from magiccube.cube import Move

While `Cube` is top-level, other related classes like `Move` remain in their submodules.

KociembaSolver

✓ from magiccube.solver import KociembaSolver

`KociembaSolver` and other solver-related classes are found within the `magiccube.solver` submodule.

This quickstart demonstrates how to instantiate a cube, scramble it, retrieve its state in Kociemba format, solve it using the Kociemba solver, and apply the solution.

from magiccube import Cube from magiccube.cube import Move from magiccube.solver import KociembaSolver # Create a 3x3x3 cube c = Cube(3) # Scramble the cube c.scramble(count=25) print('Scrambled cube:') print(c) # Get facelet colors in Kociemba format kociemba_colors = c.get_kociemba_facelet_colors() print(f'Kociemba facelet colors: {kociemba_colors}') # Solve the cube using Kociemba's algorithm solver = KociembaSolver(c) solution = solver.solve() print(f'Solution: {solution}') # Apply the solution to verify c.rotate(solution) print('Solved cube:') print(c) assert c.is_solved()

Debug

Known issues

breakingRotation notation changed in v1.2.0 to align with SiGN notation. This constrains move counts to a maximum of 2 (e.g., 'U', 'U2', 'U' for prime). Moves like 'U3' are now invalid.

fix

Update rotation strings to use SiGN notation. For example, change 'R3' to 'R'' or 'R U R2' to 'R U R2' where individual move counts are 1 or 2.

affects: >=1.2.0

breakingPublic objects like `Cube` are now exposed directly in the `magiccube` top-level namespace. Old imports like `from magiccube.cube import Cube` will still work but `from magiccube import Cube` is the new preferred way.

fix

Refactor imports to `from magiccube import Cube` for top-level objects where applicable, following the library's new structure.

affects: >=1.2.0

breakingThe minimum Python version was raised to 3.9 in v1.1.0.

fix

Ensure your development environment uses Python 3.9 or newer. Upgrade your Python interpreter if necessary.

affects: >=1.1.0

breakingThe default cube orientation was changed in v1.0.0 to match WCA scrambling orientation. This may affect algorithms or tests that implicitly relied on the previous default orientation.

fix

If your code relies on a specific initial orientation, explicitly set it or adjust your expectations of the cube's state after initialization.

affects: >=1.0.0

Errors

Common errors & fixes

AttributeError: module 'magiccube.cube' has no attribute 'Cube'

Attempting to import `Cube` from `magiccube.cube` after the v1.2.0 change which moved `Cube` to the top-level `magiccube` namespace, and some environments might not correctly resolve the old path.

fix

Change the import statement to `from magiccube import Cube`.

ValueError: Invalid move 'R3'. Move count must be 1 or 2 for SiGN notation. (Got 3)

Using a move string with a count greater than 2 (e.g., 'R3') after the v1.2.0 update to SiGN notation.

fix

Rewrite the move using SiGN notation (e.g., 'R''' or 'R' instead of 'R3'). For a 'U3' equivalent, use 'U'' or 'U PRIME'.

RuntimeError: This library requires Python 3.9 or newer. You are running 3.X.Y

Running `magiccube` v1.1.0 or newer with a Python interpreter older than 3.9.

fix

Upgrade your Python environment to version 3.9 or later. You can use `pyenv` or `conda` to manage multiple Python versions.

Upgrade

Version history

1.2.0latest on PyPI · released Apr 27, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/trincaog/magiccube ↗

packagehttps://pypi.org/project/magiccube/ ↗