{"id":21685659,"url":"https://github.com/wanyingng/blackjack","last_synced_at":"2025-03-20T11:44:49.922Z","repository":{"id":232208591,"uuid":"752512159","full_name":"wanyingng/Blackjack","owner":"wanyingng","description":"A command-line interface (CLI) implementation of the classic casino card game, Blackjack. ","archived":false,"fork":false,"pushed_at":"2024-04-08T14:00:23.000Z","size":182,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-25T12:09:04.647Z","etag":null,"topics":["ascii-art","blackjack","cli-app","comparing-card-game","console-application","object-oriented-design","object-oriented-programming","pyfiglet","pytest","python3","random","text-based-game","uml-diagram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wanyingng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-02-04T03:48:15.000Z","updated_at":"2024-04-09T03:06:17.000Z","dependencies_parsed_at":"2024-04-08T16:47:45.401Z","dependency_job_id":"0e4da983-d9bb-4562-9bd4-0c362f788782","html_url":"https://github.com/wanyingng/Blackjack","commit_stats":null,"previous_names":["xlepotato/blackjack","wanyingng/blackjack"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wanyingng%2FBlackjack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wanyingng%2FBlackjack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wanyingng%2FBlackjack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wanyingng%2FBlackjack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wanyingng","download_url":"https://codeload.github.com/wanyingng/Blackjack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244609350,"owners_count":20480779,"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":["ascii-art","blackjack","cli-app","comparing-card-game","console-application","object-oriented-design","object-oriented-programming","pyfiglet","pytest","python3","random","text-based-game","uml-diagram"],"created_at":"2024-11-25T16:22:25.624Z","updated_at":"2025-03-20T11:44:49.901Z","avatar_url":"https://github.com/wanyingng.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ch2 align=\"center\"\u003eBlackjack Game ♠\u003c/h2\u003e\n\n  \u003cp align=\"center\"\u003e\n    A command-line interface (CLI) implementation of the classic casino card game, Blackjack. \u003cbr /\u003e\n    Try your luck by fighting against a computer dealer 💻 today and strive to get a hand closest to 21 without busting!\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"#about-the-project\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#project-structure\"\u003eProject Structure\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#technical-design\"\u003eTechnical Design\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#design-choices\"\u003eDesign Choices\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgments\"\u003eAcknowledgments\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/xlepotato/Blackjack/assets/22700895/f8e46497-3d58-487c-8a01-002345424431\" width=\"550\" height=\"350\"\u003e\n\u003c/p\u003e\n\n\n### Project Structure\n\n### `main.py`\nThis file contains the main entry point of the game. It initializes the game components, such as the player, dealer, and game engine, and starts the game loop.\n\n### `blackjack/`\nThis directory contains the Python package for the Blackjack game.\n\n#### `baseplayer.py`\nDefines the `BasePlayer` abstract class, which serves as the base class for both the player and dealer classes. It contains common functionalities and attributes shared between players and the dealer.\n\n#### `player.py`\nContains the `Player` class, which represents the human player in the game. It handles player actions such as placing bets, hitting, standing, and managing the player's balance.\n\n#### `dealer.py`\nDefines the `Dealer` class, representing the game's computer dealer. It manages the dealer's actions during the game, such as hitting until reaching a certain threshold (the dealer's hand totals 17 or more) and revealing the face-down card.\n\n#### `card.py`\nContains the `Card` class, which represents a playing card in the game. It defines the properties of a card, such as its suit, rank, and value.\n\n#### `deck.py`\nDefines the `Deck` class, representing a deck of playing cards used in the game. It manages the creation, shuffling, and dealing of cards.\n\n#### `hand.py`\nContains the `Hand` class, which represents a player's/dealer's hand of cards. It manages the cards in the hand, computes the hand's total value, and handles adding new cards to the hand.\n\n#### `game.py`\nDefines the `Game` class, which manages the core logic of the Blackjack game. It orchestrates the interactions between the player, dealer, and deck, and determines the outcome of each round.\n\n#### `banner.py`\nContains the `display_banner` function, which displays the ASCII art welcome message and game rules at the start of the game.\n\n### `tests/`\nThis directory contains the essential test cases for the Blackjack game to execute correctly.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/xlepotato/Blackjack/assets/22700895/9be64fbb-d8b3-40db-b39d-b3e9425b6929\" width=\"600\" height=\"150\"\u003e\n\u003c/br\u003e\u003ci\u003eRunning test cases using pytest\u003c/i\u003e\n\u003c/p\u003e\n\n\n### Technical Design\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/xlepotato/Blackjack/assets/22700895/46058c1b-d479-41d3-b3e6-5468ad846a8b\" width=\"350\" height=\"350\"\u003e\n\u003c/br\u003e\u003ci\u003eUse Case Diagram\u003c/i\u003e\n\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/xlepotato/Blackjack/assets/22700895/0054410d-2ee5-4bc8-8dc8-b60c856f6c86\" width=\"350\" height=\"350\"\u003e\n\u003c/br\u003e\u003ci\u003eClass Diagram\u003c/i\u003e\n\u003c/p\u003e\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/xlepotato/Blackjack/assets/22700895/f36159b7-2fb5-48ff-8fab-b9f95fbef27d\" width=\"350\" height=\"350\"\u003e\n\u003c/br\u003e\u003ci\u003eActivity Diagram\u003c/i\u003e\n\u003c/p\u003e\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n## Design Choices\n- **Modular Structure**: The project is structured as a Python package (`blackjack/`) with each component (player, dealer, game logic, etc) in separate modules. This promotes code organization and reusability. Programming is much easier as the data and the code that manipulates that data are located in the same place, reducing complexity for users of that module. Based on the \u003cb\u003eSingle Responsibility Principle\u003c/b\u003e, a separate module `banner` was created to handle printing the welcome message and game rules. \n- **Object-Oriented Design**: Object-oriented programming (OOP) is a style of programming that focuses on using objects to design and build applications. In this project, the game components (player, dealer, cards, etc) are implemented as classes with well-defined attributes and responsibilities. This allows for easy extensibility and maintenance. The code is focused, succinct, and understandable to humans. Following closely with the \u003cb\u003eD.R.Y.\u003c/b\u003e or \u003cb\u003e\"Don't Repeat Yourself\" principle\u003c/b\u003e, repeated, common, or shared characteristics between two or more classes (Player and Dealer) are factored out into another class (BasePlayer). Modifications to the software are thereby easier to apply and maintain, as any changes to the code common to both subclasses need only be made once in the superclass, resulting in less code and repetition overall. \n- **CLI Interface**: The game is implemented as a command-line interface, making it portable (run effectively in different computing environments with minimal changes) and easy to play without the need for graphical user interfaces. ASCII art is used to create a simple graphic of the playing cards on the CLI.\n- **Future Considerations**: Further improvements in code quality will focus on the design principle of Encapsulation, where critical data and functions of the object are restricted to only within the object. This creates protection from unexpected direct changes to that data. Thus, preserving data integrity through the use of specific methods to access those attributes. \n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/xlepotato/Blackjack/assets/22700895/94c83b96-48a7-42b3-822a-4d50389c1054\" width=\"350\" height=\"350\"\u003e\n\u003c/br\u003e\u003ci\u003eA snapshot of the interface, showing the ASCII art representation of the playing cards\u003c/i\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nTo get a local copy up and running, follow these simple example steps.\n\n### Installation\n\n1. Clone the repo\n   ```sh\n   git clone https://github.com/xlepotato/Blackjack.git\n   ```\n2. Install all the required dependencies\n   ```sh\n   pip install -r requirements.txt\n   ```\n3. Run the application by executing the following command in the directory where main.py resides in\n   ```sh\n   python main.py\n   ```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\nThe video below is a walkthrough of the Blackjack CLI Game. \n\nhttps://github.com/xlepotato/Blackjack/assets/22700895/0c8c3f3f-1ced-4f05-a980-2c6e22c07a40\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- ACKNOWLEDGMENTS --\u003e\n## Acknowledgments\n\n* [Harvard University, CS50P 2024](https://cs50.harvard.edu/python/2022/)\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/xlepotato/Blackjack.svg?style=for-the-badge\n[contributors-url]: https://github.com/xlepotato/Blackjack/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/xlepotato/Blackjack.svg?style=for-the-badge\n[forks-url]: https://github.com/xlepotato/Blackjack/network/members\n[stars-shield]: https://img.shields.io/github/stars/xlepotato/Blackjack.svg?style=for-the-badge\n[stars-url]: https://github.com/xlepotato/Blackjack/stargazers\n[issues-shield]: https://img.shields.io/github/issues/xlepotato/Blackjack.svg?style=for-the-badge\n[issues-url]: https://github.com/xlepotato/Blackjack/issues\n[license-shield]: https://img.shields.io/github/license/xlepotato/Blackjack.svg?style=for-the-badge\n[license-url]: https://github.com/xlepotato/Blackjack/blob/main/LICENSE\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwanyingng%2Fblackjack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwanyingng%2Fblackjack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwanyingng%2Fblackjack/lists"}