{"id":13678408,"url":"https://github.com/jeffsieu/py-sudoku","last_synced_at":"2025-04-04T12:08:41.099Z","repository":{"id":45175857,"uuid":"230117469","full_name":"jeffsieu/py-sudoku","owner":"jeffsieu","description":"A Python Sudoku solver","archived":false,"fork":false,"pushed_at":"2024-10-15T18:44:26.000Z","size":46,"stargazers_count":77,"open_issues_count":3,"forks_count":21,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-17T03:57:35.140Z","etag":null,"topics":["py-sudoku","python","solves","sudoku","sudoku-generator","sudoku-solver"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/py-sudoku","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/jeffsieu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"jeffsieu","custom":null}},"created_at":"2019-12-25T14:59:05.000Z","updated_at":"2024-10-15T18:44:30.000Z","dependencies_parsed_at":"2024-06-21T04:17:20.733Z","dependency_job_id":"a2b3b372-23f3-455d-8aa2-ff6bb769cc8b","html_url":"https://github.com/jeffsieu/py-sudoku","commit_stats":{"total_commits":7,"total_committers":3,"mean_commits":"2.3333333333333335","dds":0.4285714285714286,"last_synced_commit":"5ceb5b573979a4ba84aeb2590c21e200773e9f1f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffsieu%2Fpy-sudoku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffsieu%2Fpy-sudoku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffsieu%2Fpy-sudoku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeffsieu%2Fpy-sudoku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeffsieu","download_url":"https://codeload.github.com/jeffsieu/py-sudoku/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174423,"owners_count":20896078,"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","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":["py-sudoku","python","solves","sudoku","sudoku-generator","sudoku-solver"],"created_at":"2024-08-02T13:00:53.272Z","updated_at":"2025-04-04T12:08:41.081Z","avatar_url":"https://github.com/jeffsieu.png","language":"Python","funding_links":["https://buymeacoffee.com/jeffsieu"],"categories":["Python"],"sub_categories":[],"readme":"# py-sudoku\n\nA simple Python package that generates and solves m x n Sudoku puzzles.\n\n## Install\n\n```sh\n# Python 2\npip install py-sudoku\n\n# Python 3\npip3 install py-sudoku\n```\n\n## Usage\n\n### Basic usage\n\n```py\nfrom sudoku import Sudoku\n# Initializes a Sudoku puzzle with 3 x 3 sub-grid and\n# generates a puzzle with half of the cells empty\npuzzle = Sudoku(3).difficulty(0.5)\npuzzle.show()\n# +-------+-------+-------+\n# | 4 1   | 3     | 7 6   |\n# |   9 3 |   7   | 4   1 |\n# | 2     | 1 4   |   8 3 |\n# +-------+-------+-------+\n# | 9 5 8 |       |     7 |\n# | 3 4   |     7 |   1   |\n# |   7 2 | 8 9 3 | 5 4   |\n# +-------+-------+-------+\n# |   8   | 2     | 3 7 4 |\n# |     4 |       | 1 9 5 |\n# |       |   5   | 6     |\n# +-------+-------+-------+\n\nsolution = puzzle.solve()\nsolution.show()\n# +-------+-------+-------+\n# | 4 1 5 | 3 8 9 | 7 6 2 |\n# | 8 9 3 | 6 7 2 | 4 5 1 |\n# | 2 6 7 | 1 4 5 | 9 8 3 |\n# +-------+-------+-------+\n# | 9 5 8 | 4 1 6 | 2 3 7 |\n# | 3 4 6 | 5 2 7 | 8 1 9 |\n# | 1 7 2 | 8 9 3 | 5 4 6 |\n# +-------+-------+-------+\n# | 5 8 9 | 2 6 1 | 3 7 4 |\n# | 6 2 4 | 7 3 8 | 1 9 5 |\n# | 7 3 1 | 9 5 4 | 6 2 8 |\n# +-------+-------+-------+\n\nsolution.board\n# [[4, 1, 5, 3, 8, 9, 7, 6, 2],\n#  [8, 9, 3, 6, 7, 2, 4, 5, 1],\n#  [2, 6, 7, 1, 4, 5, 9, 8, 3],\n#  [9, 5, 8, 4, 1, 6, 2, 3, 7],\n#  [3, 4, 6, 5, 2, 7, 8, 1, 9],\n#  [1, 7, 2, 8, 9, 3, 5, 4, 6],\n#  [5, 8, 9, 2, 6, 1, 3, 7, 4],\n#  [6, 2, 4, 7, 3, 8, 1, 9, 5],\n#  [7, 3, 1, 9, 5, 4, 6, 2, 8]]\n\nsolution.width\n# 3\n\nsolution.height\n# 3\n```\n\n### Creating puzzles\n\nm x n rectangular puzzles can be initialized using the `Sudoku(width)` or `Sudoku(width, height)` constructors.\n\n```py\n# Initializes a 3 x 5 puzzle\npuzzle = Sudoku(3, 5)\n# Initializes a 4 x 4 puzzle\npuzzle = Sudoku(4)\npuzzle = Sudoku(4, 4)\n```\n\nUse ```solve()``` to get a solved puzzle, or ```difficulty(x)``` to create a problem.\n\n```py\n# Create a 3 x 5 sub-grid problem with 0.4 difficulty (40% of cells empty)\npuzzle = Sudoku(3, 5).difficulty(0.4)\n\n# Create a solved 4 x 4 problem\npuzzle = Sudoku(4).solve()\n```\n\n### Displaying puzzles\n\n```py\nsolution = Sudoku(5, 3).solve()\n\n# Shows the puzzle only\nsolution.show()\n# +----------------+----------------+----------------+\n# | 09 10 11 04 06 | 05 01 03 12 13 | 08 14 15 02 07 |\n# | 03 05 07 08 01 | 02 14 15 09 04 | 06 10 11 12 13 |\n# | 12 02 13 14 15 | 07 10 06 11 08 | 01 03 04 05 09 |\n# +----------------+----------------+----------------+\n# | 13 14 06 11 08 | 15 07 09 02 12 | 10 01 05 03 04 |\n# | 10 03 15 05 02 | 13 04 08 14 01 | 12 09 07 11 06 |\n# | 01 07 04 09 12 | 03 05 10 06 11 | 13 02 08 15 14 |\n# +----------------+----------------+----------------+\n# | 07 13 08 15 05 | 12 11 04 10 03 | 14 06 09 01 02 |\n# | 06 01 12 03 09 | 08 02 07 15 14 | 11 13 10 04 05 |\n# | 04 11 10 02 14 | 06 09 01 13 05 | 15 08 12 07 03 |\n# +----------------+----------------+----------------+\n# | 08 12 02 06 10 | 01 13 11 05 07 | 03 04 14 09 15 |\n# | 05 15 09 13 11 | 14 03 12 04 10 | 02 07 06 08 01 |\n# | 14 04 01 07 03 | 09 06 02 08 15 | 05 11 13 10 12 |\n# +----------------+----------------+----------------+\n# | 11 09 03 12 13 | 10 15 14 07 02 | 04 05 01 06 08 |\n# | 15 06 14 01 04 | 11 08 05 03 09 | 07 12 02 13 10 |\n# | 02 08 05 10 07 | 04 12 13 01 06 | 09 15 03 14 11 |\n# +----------------+----------------+----------------+\n\n\n# Use print or show_full to display more information\nprint(solution)\nsolution.show_full()\n# ---------------------------\n# 15x15 (5x3) SUDOKU PUZZLE\n# Difficulty: SOLVED\n# ---------------------------\n# +----------------+----------------+----------------+\n# | 09 10 11 04 06 | 05 01 03 12 13 | 08 14 15 02 07 |\n# | 03 05 07 08 01 | 02 14 15 09 04 | 06 10 11 12 13 |\n# | 12 02 13 14 15 | 07 10 06 11 08 | 01 03 04 05 09 |\n# +----------------+----------------+----------------+\n# | 13 14 06 11 08 | 15 07 09 02 12 | 10 01 05 03 04 |\n# | 10 03 15 05 02 | 13 04 08 14 01 | 12 09 07 11 06 |\n# | 01 07 04 09 12 | 03 05 10 06 11 | 13 02 08 15 14 |\n# +----------------+----------------+----------------+\n# | 07 13 08 15 05 | 12 11 04 10 03 | 14 06 09 01 02 |\n# | 06 01 12 03 09 | 08 02 07 15 14 | 11 13 10 04 05 |\n# | 04 11 10 02 14 | 06 09 01 13 05 | 15 08 12 07 03 |\n# +----------------+----------------+----------------+\n# | 08 12 02 06 10 | 01 13 11 05 07 | 03 04 14 09 15 |\n# | 05 15 09 13 11 | 14 03 12 04 10 | 02 07 06 08 01 |\n# | 14 04 01 07 03 | 09 06 02 08 15 | 05 11 13 10 12 |\n# +----------------+----------------+----------------+\n# | 11 09 03 12 13 | 10 15 14 07 02 | 04 05 01 06 08 |\n# | 15 06 14 01 04 | 11 08 05 03 09 | 07 12 02 13 10 |\n# | 02 08 05 10 07 | 04 12 13 01 06 | 09 15 03 14 11 |\n# +----------------+----------------+----------------+\n```\n\n### Seeds\n\nProblems can be generated with a certain seed.\n\n```py\n# Generates a 3x2 puzzle with a given seed\nSudoku(3, 2, seed=100).solve().show()\n# +-------+-------+\n# | 5 6 3 | 1 2 4 |\n# | 2 1 4 | 5 3 6 |\n# +-------+-------+\n# | 1 5 2 | 6 4 3 |\n# | 3 4 6 | 2 5 1 |\n# +-------+-------+\n# | 6 3 5 | 4 1 2 |\n# | 4 2 1 | 3 6 5 |\n# +-------+-------+\n\n```\n\n### Importing boards\n\nPuzzle boards can also be imported.\n\n```py\nboard = [\n    [0,0,7,0,4,0,0,0,0],\n    [0,0,0,0,0,8,0,0,6],\n    [0,4,1,0,0,0,9,0,0],\n    [0,0,0,0,0,0,1,7,0],\n    [0,0,0,0,0,6,0,0,0],\n    [0,0,8,7,0,0,2,0,0],\n    [3,0,0,0,0,0,0,0,0],\n    [0,0,0,1,2,0,0,0,0],\n    [8,6,0,0,7,0,0,0,5]\n]\npuzzle = Sudoku(3, 3, board=board)\n\nprint(puzzle)\n# ---------------------------\n# 9x9 (3x3) SUDOKU PUZZLE\n# Difficulty: 0.74\n# ---------------------------\n# +-------+-------+-------+\n# |     7 |   4   |       |\n# |       |     8 |     6 |\n# |   4 1 |       | 9     |\n# +-------+-------+-------+\n# |       |       | 1 7   |\n# |       |     6 |       |\n# |     8 | 7     | 2     |\n# +-------+-------+-------+\n# | 3     |       |       |\n# |       | 1 2   |       |\n# | 8 6   |   7 0 |     5 |\n# +-------+-------+-------+\n\npuzzle.solve().show_full()\n# ---------------------------\n# 9x9 (3x3) SUDOKU PUZZLE\n# Difficulty: SOLVED\n# ---------------------------\n# +-------+-------+-------+\n# | 9 8 7 | 6 4 2 | 5 3 1 |\n# | 2 3 5 | 9 1 8 | 7 4 6 |\n# | 6 4 1 | 5 3 7 | 9 8 2 |\n# +-------+-------+-------+\n# | 5 2 6 | 3 8 4 | 1 7 9 |\n# | 1 7 3 | 2 9 6 | 8 5 4 |\n# | 4 9 8 | 7 5 1 | 2 6 3 |\n# +-------+-------+-------+\n# | 3 1 9 | 8 6 5 | 4 2 7 |\n# | 7 5 4 | 1 2 3 | 6 9 8 |\n# | 8 6 2 | 4 7 9 | 3 1 5 |\n# +-------+-------+-------+\n```\n\n### Invalid boards\n\nInvalid boards give errors when attempted to be solved.\n\n```py\nboard = [\n    [0,0,7,0,4,0,0,0,0],\n    [0,0,0,0,0,8,0,0,6],\n    [0,4,1,0,0,0,9,0,0],\n    [0,0,0,0,0,0,1,7,0],\n    [0,0,0,0,0,6,0,0,0],\n    [0,0,8,7,0,0,2,0,0],\n    [3,0,0,0,0,0,0,0,0],\n    [0,0,0,1,2,0,0,0,0],\n    [8,6,0,0,7,6,0,0,5]\n]\npuzzle = Sudoku(3, 3, board=board)\n\npuzzle.show_full()\n# ---------------------------\n# 9x9 (3x3) SUDOKU PUZZLE\n# Difficulty: 0.74\n# ---------------------------\n# +-------+-------+-------+\n# |     7 |   4   |       |\n# |       |     8 |     6 |\n# |   4 1 |       | 9     |\n# +-------+-------+-------+\n# |       |       | 1 7   |\n# |       |     6 |       |\n# |     8 | 7     | 2     |\n# +-------+-------+-------+\n# | 3     |       |       |\n# |       | 1 2   |       |\n# | 8 6   |   7 6 |     5 |\n# +-------+-------+-------+\n\npuzzle.solve().show_full()\n# ---------------------------\n# 9x9 (3x3) SUDOKU PUZZLE\n# Difficulty: INVALID PUZZLE (GIVEN PUZZLE HAS NO SOLUTION)\n# ---------------------------\n# +-------+-------+-------+\n# |       |       |       |\n# |       |       |       |\n# |       |       |       |\n# +-------+-------+-------+\n# |       |       |       |\n# |       |       |       |\n# |       |       |       |\n# +-------+-------+-------+\n# |       |       |       |\n# |       |       |       |\n# |       |       |       |\n# +-------+-------+-------+\n```\n\nIf you wish to raise an `UnsolvableSudoku` error when the board is invalid pass a `raising=True` parameter:\n\n```py\npuzzle.solve(raising=True)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffsieu%2Fpy-sudoku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffsieu%2Fpy-sudoku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffsieu%2Fpy-sudoku/lists"}