diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml new file mode 100644 index 00000000..c04a3324 --- /dev/null +++ b/.github/workflows/doxygen.yml @@ -0,0 +1,31 @@ +name: Doxygen Docs + +on: + push: + tags: + - "v*" + +jobs: + docs: + name: Generate Doxygen documentation + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Doxygen + run: | + sudo apt-get update + sudo apt-get install -y doxygen + + - name: Generate documentation + working-directory: laboratories/cicd-documentation + run: doxygen Doxyfile + + - name: Upload documentation artifact + uses: actions/upload-artifact@v4 + with: + name: doxygen-html + path: laboratories/cicd-documentation/html + diff --git a/.github/workflows/run.yml b/.github/workflows/run.yml index b30ae9b0..d213e6bd 100644 --- a/.github/workflows/run.yml +++ b/.github/workflows/run.yml @@ -1,20 +1,25 @@ -name: cicd-documentation +name: Unit Tests on: - workflow_dispatch: + pull_request: + branches: + - main + types: + - opened jobs: - run: - name: 🚀 Run + test: + name: Run unit tests runs-on: ubuntu-latest steps: - - name: 📥 Checkout + - name: Checkout uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 with: - fetch-depth: 0 + python-version: "3.x" - - name: 🚀 Run - shell: bash - run: | - cd laboratories/cicd-documentation - python3 main.py + - name: Run unit tests + working-directory: laboratories/cicd-documentation + run: python -m unittest -v diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..21b6d428 --- /dev/null +++ b/.gitignore @@ -0,0 +1,67 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Type checkers +.mypy_cache/ +.dmypy.json +dmypy.json +.pyre/ +.pytype/ + +# Editors +.idea/ +.vscode/ + +# Generated documentation +laboratories/cicd-documentation/html/ +laboratories/cicd-documentation/latex/ + diff --git a/laboratories/cicd-documentation/.gitignore b/laboratories/cicd-documentation/.gitignore deleted file mode 100644 index 68bc17f9..00000000 --- a/laboratories/cicd-documentation/.gitignore +++ /dev/null @@ -1,160 +0,0 @@ -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: -# .python-version - -# pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock - -# poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock - -# pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm.fming.dev/#use-with-ide -.pdm.toml - -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Spyder project settings -.spyderproject -.spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ diff --git a/laboratories/cicd-documentation/Doxyfile b/laboratories/cicd-documentation/Doxyfile new file mode 100644 index 00000000..2b519cf1 --- /dev/null +++ b/laboratories/cicd-documentation/Doxyfile @@ -0,0 +1,22 @@ +PROJECT_NAME = "Tree traversal" +PROJECT_BRIEF = "Binary tree traversals and search operations." +OUTPUT_DIRECTORY = +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +USE_MDFILE_AS_MAINPAGE = README.md +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +FULL_PATH_NAMES = NO +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +RECURSIVE = NO +INPUT = README.md main.py node.py tree.py +FILE_PATTERNS = *.py *.md +EXTENSION_MAPPING = py=Python +GENERATE_HTML = YES +HTML_OUTPUT = html +GENERATE_LATEX = NO +QUIET = YES +WARN_IF_UNDOCUMENTED = YES diff --git a/laboratories/cicd-documentation/main.py b/laboratories/cicd-documentation/main.py index 4f48e7db..fa1916fd 100644 --- a/laboratories/cicd-documentation/main.py +++ b/laboratories/cicd-documentation/main.py @@ -1,5 +1,4 @@ from tree import Tree -from node import Node tree = Tree() diff --git a/laboratories/cicd-documentation/node.py b/laboratories/cicd-documentation/node.py index af19ada1..6ad65102 100644 --- a/laboratories/cicd-documentation/node.py +++ b/laboratories/cicd-documentation/node.py @@ -1,8 +1,10 @@ +from typing import Optional + + class Node: """ Node class for binary tree """ - def __init__(self, data): - self.left = None - self.right = None + def __init__(self, data: int) -> None: + self.left: Optional["Node"] = None + self.right: Optional["Node"] = None self.data = data - diff --git a/laboratories/cicd-documentation/test_tree.py b/laboratories/cicd-documentation/test_tree.py new file mode 100644 index 00000000..c5986f2b --- /dev/null +++ b/laboratories/cicd-documentation/test_tree.py @@ -0,0 +1,78 @@ +import unittest + +from node import Node +from tree import Tree + + +class TestTreeFind(unittest.TestCase): + def setUp(self) -> None: + self.tree = Tree() + for value in [5, 3, 8, 1, 4, 7, 9, 0, 2, 6]: + self.tree.add(value) + + def root(self) -> Node: + root = self.tree.root + assert root is not None + return root + + def assertFindsValue(self, value: int) -> Node: + node = self.tree.find(value) + + assert node is not None + self.assertEqual(value, node.data) + return node + + def test_find_returns_none_for_empty_tree(self) -> None: + empty_tree = Tree() + + self.assertIsNone(empty_tree.find(5)) + + def test_find_returns_root_node_when_value_is_root(self) -> None: + node = self.tree.find(5) + + assert node is not None + self.assertIs(node, self.root()) + self.assertEqual(5, node.data) + + def test_find_returns_existing_values_from_all_tree_levels(self) -> None: + for value in [5, 3, 8, 1, 4, 7, 9, 0, 2, 6]: + with self.subTest(value=value): + self.assertFindsValue(value) + + def test_find_returns_nodes_from_left_and_right_subtrees(self) -> None: + left_node = self.tree.find(3) + right_node = self.tree.find(8) + root = self.root() + + self.assertIs(left_node, root.left) + self.assertIs(right_node, root.right) + + def test_find_returns_none_when_value_does_not_exist_between_nodes(self) -> None: + node = self.tree.find(10) + + self.assertIsNone(node) + + def test_find_returns_none_when_value_is_below_minimum(self) -> None: + node = self.tree.find(-1) + + self.assertIsNone(node) + + def test_find_returns_none_when_value_is_above_maximum(self) -> None: + node = self.tree.find(12) + + self.assertIsNone(node) + + def test_private_find_returns_node_when_value_exists(self) -> None: + node = self.tree._find(2, self.root()) + + assert node is not None + self.assertEqual(2, node.data) + + def test_private_find_returns_none_when_value_does_not_exist(self) -> None: + node = self.tree._find(11, self.root()) + + self.assertIsNone(node) + + +if __name__ == '__main__': + unittest.main() diff --git a/laboratories/cicd-documentation/tree.py b/laboratories/cicd-documentation/tree.py index 2639fcd1..9a1f06f4 100644 --- a/laboratories/cicd-documentation/tree.py +++ b/laboratories/cicd-documentation/tree.py @@ -1,32 +1,32 @@ +from typing import Optional + from node import Node class Tree: - """ Tree class for binary tree """ + """Represent a binary search tree.""" - def __init__(self): - """ Constructor for Tree class """ - self.root = None + def __init__(self) -> None: + """Initialize an empty tree.""" + self.root: Optional[Node] = None - def getRoot(self): - """ Method for get root of the tree """ + def getRoot(self) -> Optional[Node]: + """Return the root node of the tree.""" return self.root - def add(self, data): - """ Method for add data to the tree """ + def add(self, data: int) -> None: + """Insert a value into the tree.""" if self.root is None: self.root = Node(data) else: self._add(data, self.root) - def _add(self, data, node): - """Method for add data to the tree + def _add(self, data: int, node: Node) -> None: + """Insert a value into the subtree rooted at ``node``. Args: - data (int): data to add - - Returns: - None + data (int): Value to insert. + node (Node): Root of the subtree where the value is inserted. """ if data < node.data: if node.left is not None: @@ -39,47 +39,64 @@ def _add(self, data, node): else: node.right = Node(data) - def find(self, data): - """Method for find data in the tree + def find(self, data: int) -> Optional[Node]: + """Find a value in the tree. Args: - data (int): data to find + data (int): Value to search for. Returns: - Node: node with data + Optional[Node]: Matching node if the value exists, otherwise ``None``. """ if self.root is not None: return self._find(data, self.root) else: return None - def _find(self, data, node): + def _find(self, data: int, node: Node) -> Optional[Node]: + """Search for a value inside the subtree rooted at ``node``. + + Args: + data (int): Value to search for. + node (Node): Current subtree root used during recursion. + + Returns: + Optional[Node]: Matching node if found, otherwise ``None``. + """ if data == node.data: return node elif (data < node.data and node.left is not None): return self._find(data, node.left) elif (data > node.data and node.right is not None): return self._find(data, node.right) + return None - def deleteTree(self): + def deleteTree(self) -> None: + """Remove all nodes from the tree.""" self.root = None - def printTree(self): + def printTree(self) -> None: + """Print the tree using in-order traversal.""" if self.root is not None: self._printInorderTree(self.root) - def _printInorderTree(self, node): + def _printInorderTree(self, node: Optional[Node]) -> None: + """Print the subtree rooted at ``node`` in in-order.""" if node is not None: self._printInorderTree(node.left) print(str(node.data) + ' ') self._printInorderTree(node.right) - def _printPreorderTree(self, node): - # TODO - pass - - def _printPostorderTree(self, node): - # TODO - pass - + def _printPreorderTree(self, node: Optional[Node]) -> None: + """Print the subtree rooted at ``node`` in pre-order.""" + if node is not None: + print(str(node.data) + ' ') + self._printPreorderTree(node.left) + self._printPreorderTree(node.right) + def _printPostorderTree(self, node: Optional[Node]) -> None: + """Print the subtree rooted at ``node`` in post-order.""" + if node is not None: + self._printPostorderTree(node.left) + self._printPostorderTree(node.right) + print(str(node.data) + ' ')