Aces High: Core Python Library

A Python library for modeling playing cards, decks, and core logic for traditional card games. Built with clean, testable design principles and designed to serve as the foundation for more complex gameplay logic.

🧠 Built to teach — this library powers the examples in the companion eBook:
Building Systems Like a Senior Engineer

Features

• 🎴 Card and Deck modeling using Pythonic, enum-safe data structures
• 🔁 Standard shuffling, dealing, and deck state management
• 🧪 Fully tested with pytest, using a test-first design process
• 🧹 Enforced code quality via black and ruff
• 📦 Easy-to-install package, published to PyPI

Installation

pip install aces-high-core-py

Usage

from aces_high import StandardDeck

deck = StandardDeck()
deck.shuffle()

hand = deck.deal(5)
for card in hand:
    print(card)

Development

Clone the repo and install dependencies with uv:

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Run tests:

pytest

Format and lint:

black src/ tests/
ruff check src/ tests/

Publishing

We use uv publish and workflow_dispatch in GitHub Actions for controlled PyPI deploys. See the Publish to PyPI workflow for more.

License

MIT License © Aaron Smith

See Also

📘 Aces High eBook — Learn how this library was designed and built from scratch, with a focus on practical system design and senior engineering practices.