pingv4 0.1.0__tar.gz

pingv4-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+*.so
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Rust
+target/

pingv4-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

pingv4-0.1.0/Cargo.lock

@@ -0,0 +1,180 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.180"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bcc35a38544a891a5f7c865aca548a982ccb3b8650a5b06d0fd33a10283c56fc"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
+[[package]]
+name = "pingv4"
+version = "0.1.0"
+dependencies = [
+ "pyo3",
+]
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f89776e4d69bb58bc6993e99ffa1d11f228b839984854c7daeb5d37f87cbe950"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21b2ebcf727b7760c461f091f9f0f539b77b8e87f2fd88131e7f1b433b3cece4"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "syn"
+version = "2.0.114"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4d107df263a3013ef9b1879b0df87d706ff80f65a86ea879bd9c31f9b307c2a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

pingv4-0.1.0/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "pingv4"
+version = "0.1.0"
+edition = "2021"
+readme = "README.md"
+
+[lib]
+name = "_core"
+# "cdylib" is necessary to produce a shared library for Python to import from.
+crate-type = ["cdylib"]
+
+[dependencies]
+# "extension-module" tells pyo3 we want to build an extension module (skips linking against libpython.so)
+# "abi3-py39" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.9
+pyo3 = { version = "0.22.4", features = ["extension-module", "abi3-py39"] }

pingv4-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Developer Student Club - SNU
+
+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.

pingv4-0.1.0/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: pingv4
+Version: 0.1.0
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pygame>=2.6.1
+License-File: LICENSE
+Summary: A high-performance Connect Four library with a graphical game interface and bot framework.
+Author-email: lalitm1004 <lalitm1004@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/dscsnu/pingv4
+Project-URL: Homepage, https://github.com/dscsnu/pingv4
+Project-URL: Issues, https://github.com/dscsnu/pingv4/issues
+
+# pingv4
+
+A high-performance Connect Four library with a graphical game interface and bot framework.
+
+## Installation
+
+```bash
+pip install pingv4
+```
+> *Note: Python 3.9+ required*
+
+## Quick Start
+
+### Play a Game
+
+```python
+from pingv4 import Connect4Game, MinimaxBot
+
+# Human vs Human
+game = Connect4Game()
+game.run()
+
+# Human vs Bot
+game = Connect4Game(player1=None, player2=MinimaxBot)
+game.run()
+
+# Bot vs Bot
+game = Connect4Game(player1=MinimaxBot, player2=MinimaxBot)
+game.run()
+```
+
+### Use the Board Directly
+
+```python
+from pingv4 import ConnectFourBoard, CellState
+
+board = ConnectFourBoard()
+
+# Make moves (returns a new board - immutable!)
+board = board.make_move(3)  # Red plays center
+board = board.make_move(3)  # Yellow plays center
+board = board.make_move(2)  # Red plays left of center
+
+# Check game state
+print(board.is_in_progress)  # True
+print(board.current_player)  # CellState.Yellow
+print(board.get_valid_moves())  # [0, 1, 2, 3, 4, 5, 6]
+
+# Access cells (column-major: board[col, row])
+print(board[3, 0])  # CellState.Red
+print(board[3, 1])  # CellState.Yellow
+
+# Print the board
+print(board)
+```
+
+---
+
+## API Reference
+
+### `CellState`
+
+An enum representing the state of a cell.
+
+```python
+from pingv4 import CellState
+
+CellState.Red     # Red player (plays first)
+CellState.Yellow  # Yellow player
+```
+
+---
+
+### `ConnectFourBoard`
+
+The core game board class. **Immutable** - all operations return new board instances.
+
+#### Creating a Board
+
+```python
+board = ConnectFourBoard()  # Creates an empty 6x7 board
+```
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `num_rows` | `int` | Number of rows (6) |
+| `num_cols` | `int` | Number of columns (7) |
+| `current_player` | `CellState \| None` | Current player, or `None` if game over |
+| `is_in_progress` | `bool` | `True` if game is still ongoing |
+| `is_victory` | `bool` | `True` if a player has won |
+| `is_draw` | `bool` | `True` if the board is full with no winner |
+| `winner` | `CellState \| None` | The winning player, or `None` |
+| `column_heights` | `list[int]` | Number of pieces in each column |
+| `hash` | `int` | Deterministic hash for the board state |
+| `cell_states` | `list[list[CellState \| None]]` | All cells (column-major) |
+
+#### Methods
+
+```python
+# Get valid moves (columns that aren't full)
+moves: list[int] = board.get_valid_moves()
+
+# Make a move (returns NEW board)
+new_board = board.make_move(col_idx)  # col_idx: 0-6
+
+# Access a cell (column-major!)
+cell = board[col, row]  # col: 0-6, row: 0-5 (bottom to top)
+```
+
+> ⚠️ **Column-Major Access**: Board indexing is `board[column, row]`, not `board[row, column]`.
+
+#### Example: Game Loop
+
+```python
+from pingv4 import ConnectFourBoard
+
+board = ConnectFourBoard()
+
+while board.is_in_progress:
+    move = int(input(f"{board.current_player}'s turn. Column (0-6): "))
+    if move in board.get_valid_moves():
+        board = board.make_move(move)
+    print(board)
+
+if board.is_victory:
+    print(f"{board.winner} wins!")
+else:
+    print("It's a draw!")
+```
+
+---
+
+### `Connect4Game`
+
+A pygame-based graphical game interface.
+
+```python
+from pingv4 import Connect4Game, GameConfig, MinimaxBot
+
+# Basic usage
+game = Connect4Game(
+    player1=None,        # Human player
+    player2=MinimaxBot,  # Bot class
+    config=GameConfig()  # Optional configuration
+)
+game.run()
+```
+
+#### Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `player1` | `PlayerConfig` | `None` | First player (see below) |
+| `player2` | `PlayerConfig` | `None` | Second player |
+| `config` | `GameConfig` | `GameConfig()` | Game settings |
+
+**`PlayerConfig`** can be:
+- `None` — Human player (manual input)
+- Bot class (e.g., `MinimaxBot`, `RandomBot`) — Will be instantiated automatically
+
+#### Controls
+
+| Key | Action |
+|-----|--------|
+| Click | Place piece (human turn) |
+| `R` | Restart game |
+| `ESC` | Quit |
+
+---
+
+### `GameConfig`
+
+Frozen Pydantic model for game configuration.
+
+```python
+from pingv4 import GameConfig
+
+config = GameConfig(
+    bot_delay_seconds=0.5,      # Delay before bot moves (default: 1.0)
+    animation_speed=35,          # Piece falling speed (default: 25)
+    window_width=700,            # Window width in pixels
+    window_height=700,           # Window height in pixels
+    cell_size=80,                # Size of each cell
+    background_color=(30, 30, 40),
+    board_color=(0, 80, 180),
+    red_color=(220, 50, 50),
+    yellow_color=(240, 220, 50),
+)
+```
+
+---
+
+## Creating Custom Bots
+
+Extend `AbstractBot` to create your own Connect Four AI:
+
+```python
+from pingv4 import AbstractBot, ConnectFourBoard, CellState
+
+class MyBot(AbstractBot):
+    @property
+    def strategy_name(self) -> str:
+        return "My Custom Bot"
+    
+    @property
+    def author_name(self) -> str:
+        return "Your Name"
+    
+    @property
+    def author_netid(self) -> str:
+        return "your_id"
+    
+    def get_move(self, board: ConnectFourBoard) -> int:
+        """Return a column index (0-6) for your move."""
+        valid_moves = board.get_valid_moves()
+        
+        # Your strategy here!
+        # Example: prefer center columns
+        for col in [3, 2, 4, 1, 5, 0, 6]:
+            if col in valid_moves:
+                return col
+        
+        return valid_moves[0]
+```
+
+### Using Your Bot
+
+```python
+from pingv4 import Connect4Game
+
+game = Connect4Game(player1=MyBot, player2=None)
+game.run()
+```
+
+### Bot Interface
+
+Your bot receives a `ConnectFourBoard` and must return a valid column index.
+
+```python
+def get_move(self, board: ConnectFourBoard) -> int:
+    # Useful properties:
+    board.current_player      # Your color (CellState.Red or CellState.Yellow)
+    board.get_valid_moves()   # List of valid columns
+    board.column_heights      # How full each column is
+    board.hash                # For transposition tables
+    
+    # Simulate moves:
+    future = board.make_move(col)  # Returns new board
+    
+    # Check outcomes:
+    future.is_victory  # Did someone win?
+    future.winner      # Who won?
+    
+    return column_index  # 0-6
+```
+
+---
+
+## Built-in Bots
+
+### `RandomBot`
+
+Plays random valid moves. Useful for testing.
+
+```python
+from pingv4 import RandomBot
+```
+
+### `MinimaxBot`
+
+Strong AI using minimax with alpha-beta pruning.
+
+```python
+from pingv4 import MinimaxBot
+
+# Default depth is 6
+game = Connect4Game(player1=MinimaxBot, player2=MinimaxBot)
+```
+
+Features:
+- Alpha-beta pruning
+- Transposition tables (using `board.hash`)
+- Center-preference move ordering
+- Positional evaluation
+
+---
+
+## Tips for Bot Development
+
+### Use the Hash for Caching
+
+The `board.hash` property is highly optimized. Use it for transposition tables:
+
+```python
+cache = {}
+
+def evaluate(board):
+    if board.hash in cache:
+        return cache[board.hash]
+    
+    score = expensive_calculation(board)
+    cache[board.hash] = score
+    return score
+```
+
+### Board is Immutable
+
+`make_move()` returns a new board. The original is unchanged:
+
+```python
+board1 = ConnectFourBoard()
+board2 = board1.make_move(3)
+
+board1[3, 0]  # None (unchanged)
+board2[3, 0]  # CellState.Red
+```
+
+### Column-Major Access
+
+Remember: it's `board[column, row]`, not `board[row, column]`.
+
+```python
+# Check if column 3 has a red piece at the bottom
+if board[3, 0] == CellState.Red:
+    ...
+```