[Sync Iteration] python/collatz-conjecture/1

.github/workflows/pylint.yml

@@ -0,0 +1,28 @@
+name: Pylint
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint
+        pip install -r requirements.txt
+    - name: Analysing the code with pylint
+      run: |
+        python -m pylint --verbose $(find . -name "*.py" ! -path "*/.venv/*" ! -path "*/venv/*") --rcfile=.pylintrc

.github/workflows/pytest.yml

@@ -0,0 +1,29 @@
+name: Pytest Workflow
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install pytest
+
+    - name: Run pytest
+      run: pytest --verbose --ignore=solutions

.pylintrc

@@ -0,0 +1,3 @@
+[MASTER]
+ignore=.venv
+ignore-paths=^(.*/|)solutions/.*$

README.md

@@ -1,5 +1,22 @@
-# Exercism Python Track
+# [Exercism Python Track](https://exercism.io/my/tracks/python)
 
-Learn and master concepts to achieve fluency in Python.
+<div align="center"> 
+<img width="10%" height="10%" src="https://github.com/ikostan/Exercism_Python_Track/blob/master/img/exercism-logo.png" hspace="20">
+<img width="9%" height="9%" src="https://github.com/ikostan/Exercism_Python_Track/blob/master/img/python-track.png" hspace="20">
+</div>
+
+## Exercism exercises in Python
+
+### About Exercism
+Exercism is an online platform designed to help you improve your coding skills through practice and mentorship.
+
+Exercism provides you with thousands of exercises spread across numerous language tracks. Once you start a language track you are presented with a core set of exercises to complete. Each one is a fun and interesting challenge designed to teach you a little more about the features of a language.
+
+You complete a challenge by downloading the exercise to your computer and solving it in your normal working environment. Once you've finished you submit it online and one of our mentors will give you feedback on how you could improve it using features of the language that you may not be familiar with. After a couple of rounds of refactoring, your exercise will be complete and you will unlock both the next core exercise and also a series of related side-exercises for you to practice with.
+
+Exercism is entirely open source and relies on the contributions of thousands of wonderful people.
+
+Exercism is designed to be fun and friendly, and we place a strong emphasis on empathetic communication. 
+
+Sign up and have fun. Exercism is 100% free :)
 
-143 coding exercises for Python on Exercism. From Error Handling to ISBN Verifier.

armstrong-numbers/armstrong_numbers_test.py

@@ -1,3 +1,46 @@
+# pylint: disable=C0301
+"""
+Armstrong Numbers Test Suite Documentation
+
+## Overview
+
+This test suite validates the `is_armstrong_number` function,
+ensuring its correct behavior for various types of numbers:
+
+- Single-digit and multi-digit numbers
+- Known Armstrong numbers and non-Armstrong numbers
+
+Tests are auto-generated based on canonical data from
+[Exercism problem specifications](https://github.com/exercism/problem-specifications/tree/main/exercises/armstrong-numbers/canonical-data.json).
+
+## Structure
+
+- **Framework:** Uses Python's built-in `unittest`.
+- **Target Function:** `is_armstrong_number` (imported from `armstrong_numbers` module).
+
+## Test Cases
+
+| Test Description                                        | Input    | Expected Output |
+|---------------------------------------------------------|----------|-----------------|
+| Zero is an Armstrong number                             | 0        | `True`          |
+| Single-digit numbers are Armstrong numbers              | 5        | `True`          |
+| No two-digit numbers (e.g. 10) are Armstrong numbers    | 10       | `False`         |
+| 153 is an Armstrong number                              | 153      | `True`          |
+| 100 is not an Armstrong number                          | 100      | `False`         |
+| 9474 is an Armstrong number                             | 9474     | `True`          |
+| 9475 is not an Armstrong number                         | 9475     | `False`         |
+| 9926315 is an Armstrong number                          | 9926315  | `True`          |
+| 9926314 is not an Armstrong number                      | 9926314  | `False`         |
+
+## Usage
+
+To run the tests, ensure `is_armstrong_number` is implemented and run:
+
+```bash
+python -m unittest armstrong_numbers_test.py
+
+"""
+
 # These tests are auto-generated with test data from:
 # https://github.com/exercism/problem-specifications/tree/main/exercises/armstrong-numbers/canonical-data.json
 # File last updated on 2023-07-20
@@ -10,29 +53,88 @@
 
 
 class ArmstrongNumbersTest(unittest.TestCase):
+    """Armstrong Numbers Test."""
+
     def test_zero_is_an_armstrong_number(self):
+        """
+        Test that zero is correctly identified as an Armstrong number.
+
+        This test verifies that the function correctly determines that 0
+        is an Armstrong number, as 0^1 == 0.
+
+        :returns: None
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(0), True)
 
     def test_single_digit_numbers_are_armstrong_numbers(self):
+        """
+        Test that all single digit numbers are Armstrong numbers.
+
+        :returns: None. Asserts that a single digit number (e.g., 5) is an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(5), True)
 
     def test_there_are_no_two_digit_armstrong_numbers(self):
+        """
+        Test that no two-digit numbers are Armstrong numbers.
+
+        :returns: None. Asserts that a two-digit number (e.g., 10) is not an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(10), False)
 
     def test_three_digit_number_that_is_an_armstrong_number(self):
+        """
+        Test that 153 is correctly identified as an Armstrong number.
+
+        :returns: None. Asserts that 153 is an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(153), True)
 
     def test_three_digit_number_that_is_not_an_armstrong_number(self):
+        """
+        Test that 100 is not identified as an Armstrong number.
+
+        :returns: None. Asserts that 100 is not an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(100), False)
 
     def test_four_digit_number_that_is_an_armstrong_number(self):
+        """
+        Test that 9474 is correctly identified as an Armstrong number.
+
+        :returns: None. Asserts that 9474 is an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(9474), True)
 
     def test_four_digit_number_that_is_not_an_armstrong_number(self):
+        """
+        Test that 9475 is not identified as an Armstrong number.
+
+        :returns: None. Asserts that 9475 is not an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(9475), False)
 
     def test_seven_digit_number_that_is_an_armstrong_number(self):
+        """
+        Test that 9926315 is correctly identified as an Armstrong number.
+
+        :returns: None. Asserts that 9926315 is an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(9926315), True)
 
     def test_seven_digit_number_that_is_not_an_armstrong_number(self):
+        """
+        Test that 9926314 is not identified as an Armstrong number.
+
+        :returns: None. Asserts that 9926314 is not an Armstrong number.
+        :rtype: NoneType
+        """
         self.assertIs(is_armstrong_number(9926314), False)

black-jack/black_jack.py

@@ -19,7 +19,8 @@ def value_of_card(card) -> int:
     """
     if card in 'JKQ':
         return 10
-    elif card == 'A':
+
+    if card == 'A':
         return 1
 
     return int(card)
@@ -29,16 +30,19 @@ def higher_card(card_one, card_two) -> str | tuple[str, str]:
     """
     Determine which card has a higher value in the hand.
 
-    :param card_one, card_two: str - cards dealt in hand.  See below for values.
-    :return: str or tuple - resulting Tuple contains both cards if they are of equal value.
+    :param card_one: str - cards dealt in hand. See below for values.
+    :param card_two: str - cards dealt in hand. See below for values.
+    :return: str or tuple - resulting Tuple contains both cards if
+             they are of equal value.
 
     1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
     2.  'A' (ace card) = 1
     3.  '2' - '10' = numerical value.
     """
     if value_of_card(card_one) == value_of_card(card_two):
         return card_one, card_two
-    elif value_of_card(card_one) > value_of_card(card_two):
+
+    if value_of_card(card_one) > value_of_card(card_two):
         return card_one
 
     return card_two
@@ -56,11 +60,14 @@ def value_of_ace(card_one, card_two) -> int:
     3.  '2' - '10' = numerical value.
     """
     total: int = value_of_card(card_one) + value_of_card(card_two)
-    # Hint: if we already have an ace in hand, then the value for the upcoming ace would be 1.
+    # Hint: if we already have an ace in hand, then the value for
+    # the upcoming ace would be 1.
     if card_one == 'A' or card_two == 'A':
         return 1
-    # The value of the hand with the ace needs to be as high as possible without going over 21.
-    elif 21 - total >= 11:
+    # The value of the hand with the ace needs to be as high as
+    # possible without going over 21.
+
+    if 21 - total >= 11:
         return 11
 
     return 1
@@ -70,7 +77,10 @@ def is_blackjack(card_one, card_two) -> bool:
     """
     Determine if the hand is a 'natural' or 'blackjack'.
 
-    :param card_one, card_two: str - card dealt. See below for values.
+    :param card_one: card dealt. See below for values.
+    :type card_one: str
+    :param card_two: card dealt. See below for values.
+    :type card_two: str
     :return: bool - is the hand is a blackjack (two cards worth 21).
 
     1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
@@ -81,7 +91,8 @@ def is_blackjack(card_one, card_two) -> bool:
     # as their first two cards, then the player has a score of 21.
     if card_one == 'A' and card_two in ('J', 'Q', 'K', '10'):
         return True
-    elif card_two == 'A' and card_one in ('J', 'Q', 'K', '10'):
+
+    if card_two == 'A' and card_one in ('J', 'Q', 'K', '10'):
         return True
 
     return False
@@ -91,8 +102,10 @@ def can_split_pairs(card_one, card_two) -> bool:
     """
     Determine if a player can split their hand into two hands.
 
-    :param card_one, card_two: str - cards dealt.
-    :return: bool - can the hand be split into two pairs? (i.e. cards are of the same value).
+    :param card_one: str - cards dealt.
+    :param card_two: str - cards dealt.
+    :return: bool - can the hand be split into two pairs?
+             (i.e. cards are of the same value).
     """
     if value_of_card(card_one) == value_of_card(card_two):
         return True
@@ -104,7 +117,9 @@ def can_double_down(card_one, card_two) -> bool:
     """
     Determine if a blackjack player can place a double down bet.
 
-    :param card_one, card_two: str - first and second cards in hand.
-    :return: bool - can the hand can be doubled down? (i.e. totals 9, 10 or 11 points).
+    :param card_one: str - first and second cards in hand.
+    :param card_two: str - first and second cards in hand.
+    :return: bool - can the hand can be doubled down?
+             (i.e. totals 9, 10 or 11 points).
     """
     return 9 <= value_of_card(card_one) + value_of_card(card_two) <= 11