Initial commit

.github/ISSUE_TEMPLATE/help_wanted.md

@@ -0,0 +1,65 @@
+---
+name: help wanted 
+about: > 
+  A template issue for when you're blocked on certain lines of code. 
+  This template has many sections to get you thinking about your problem, 
+  you don't need to fill all of them. 
+labels: "help wanted"
+---
+
+<!--
+  Make your issue easy to find:
+
+  - labels: anything that will make this easier to filter
+  - assign: anyone you would like help from
+-->
+
+## The Code
+
+<!--
+  The code you have a question about (it doesn't need to be your code!). This can
+  be shared a few ways:
+
+  - a snippet in the MD of your issue or
+  - a
+    [permalink](https://help.github.com/en/github/managing-your-work-on-github/creating-a-permanent-link-to-a-code-snippet)
+    or
+  - a [gist](https://help.github.com/en/github/writing-on-github/creating-gists)
+-->
+
+## Best Understanding
+
+<!--
+  Explain the situation:
+
+  - What _does_ the code do
+  - What do you _want_ it to do
+  - How do you think it works?
+  - What don't you understand about how it works?
+-->
+
+## Best Efforts
+
+<!--
+  If this is your code and it has a bug, explain what you've tried so far:
+
+  - Include code
+  - Mention everything you tried, even if it seems silly to you
+  - What happened with each effort?
+  - What brought you closer?
+  - What brought you farther?
+-->
+
+## Helpful Links
+
+<!--
+  Videos, articles, snippets, ... anything that helped you understand or make
+  progress on the problem.
+-->
+
+## Hopeful Links
+
+<!--
+  Links that look like they should be helpful but you just can't put all the
+  pieces together.
+-->

.github/ISSUE_TEMPLATE/meeting_agenda.md

@@ -0,0 +1,26 @@
+---
+name: meeting agenda 
+about: A template issue for planning meetings 
+title: "Agenda: \_\_" 
+labels: agenda
+---
+
+
+<!-- Make your issue easy to find:
+
+  - milestone: any milestones you will be addressing
+  - tag: tag any issues you will be discussing (#issue-number)
+  - labels: anything that will make this easier to filter
+  - assign: anyone responsible for organizing or leading the meeting
+
+-->
+
+<!-- meeting overview -->
+
+<!-- agenda points -->
+
+- [ ] item 1
+  - description
+- [ ] item 2
+  - description
+- [ ] ...

.github/ISSUE_TEMPLATE/new_challenge.md

@@ -0,0 +1,21 @@
+---
+name: new challenge 
+about: > 
+  A template issue for describing a new challenge on the project board. 
+  Place this issue in the TODO column of your group's project board. 
+---
+
+<!--
+  Make your issue easy to find:
+
+  - project board: place it in the TODO column of the project board
+  - labels: anything that will make this easier to filter
+-->
+
+<!-- 
+  Describe the challenge's _behavior_ so someone can start solving it without asking for clarification.
+  Do not describe a _strategy_ or an _implementation_!  
+  Others are free to solve the behavior however they like.
+-->
+
+<!-- include any helpful links or resources for solving this challenge -->

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,15 @@
+---
+name: question 
+about: > 
+  A template issue for topics you'd like to discuss or learn more about. 
+  specific topics, general knowledge, it does not even need to be about code. 
+  There are no bad questions! 
+labels: question
+---
+
+<!--
+  Make your issue easy to find:
+
+  - labels: anything that will make this easier to filter
+  - assign: anyone you would like help from
+-->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,93 @@
+---
+name: solution review 
+about: A template PR for code review with a checklist
+---
+
+<!--
+  make this PR easy to find:
+
+  - assign: yourself
+  - link it to the corresponding challenge issue on the project board
+-->
+
+<!-- describe the challenge you will solve -->
+
+## Behavior
+
+### Files
+
+- [ ] The file name describes the function's behavior
+- [ ] There is a module header in the function file
+- [ ] There is a module docstring in the function file
+- [ ] The test file's name matches the function file name -
+  `/tests/test_file_name.py`
+- [ ] There is a module docstring in the tests file
+- [ ] There is a module header in the tests file
+
+### Unit Tests
+
+- [ ] The test class has a helpful name in PascalCase
+- [ ] The test class has a docstring
+- Every unit test has
+  - [ ] A helpful name
+  - [ ] A clear docstring
+  - [ ] Only one assertion
+  - [ ] There is no logic in the unit test
+- [ ] All tests pass
+- [ ] There are tests for defensive assertions
+- [ ] There are tests for boundary cases
+
+### Function Docstring
+
+- [ ] The function's behavior is described
+- The function's arguments are described:
+  - [ ] Type
+  - [ ] Purpose
+  - [ ] Other assumptions (eg. if it's a number, what's the expected range?)
+- The return value is described
+  - [ ] Type
+  - [ ] Other assumptions are documented
+- The defensive assertions are documented using `Raises:`
+  - [ ] Each assumption about an argument is checked with an assertion
+  - [ ] Each assertion checks for _only one_ assumption about the argument
+- [ ] Include 3 or more (passing!) doctests
+
+### The Function
+
+- [ ] The function's name describes it's behavior
+- [ ] The function's name matches the file name
+  - _It's ok to have extra helper functions, like with mergesort_
+- [ ] The function has correct type annotations
+- [ ] The function is not called at the top level of the function file 
+  - _Recursive solutions **can** call the function from **inside** the function body_
+
+## Strategy
+
+### Do's
+
+- [ ] Variable names help to understand the strategy
+- [ ] Any comments are clear and describe the strategy
+- [ ] Lines of code are spaced to help show different stages of the strategy
+
+### Don'ts
+
+- [ ] The function's strategy _is not_ described in any docstrings or tests
+- [ ] Comments explain the _strategy_, **not** the _implementation_
+- [ ] The function _does not_ have more comments than code
+  - If it does, consider finding a new strategy or a simpler implementation
+
+## Implementation
+
+- [ ] The code passes the formatting checks
+- [ ] The code passes all Ruff linting checks
+- [ ] The code has no (reasonable) Pylint errors
+  - In code review, you can decide when fixing a Pylint error is helpful and
+    when it's too restricting.
+- [ ] Variables are named with snake_case
+- [ ] Variable names are clear and helpful
+- [ ] The code follows the strategy as simply as possible
+- [ ] The implementation is as simple as possible given the strategy
+- [ ] There are no commented lines of code
+- [ ] There are no `print`  or `input` statements anywhere in the function or test files
+- [ ] The code includes defensive assertions
+- [ ] Defensive assertions include as little logic as possible

.github/workflows/ci-checks.yml

@@ -0,0 +1,80 @@
+name: ET CI Checks
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  ls_linting:
+      runs-on: ubuntu-latest
+      steps:  
+        - uses: actions/checkout@v4
+        - uses: ls-lint/action@v2.2.3
+
+  md_formatting:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: nosborn/github-action-markdown-cli@v3.3.0
+      with:
+        files: .
+        config_file: .markdownlint.yml
+
+  py_formatting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Python - Check Formatting
+        uses: astral-sh/ruff-action@v1
+        with:
+          args: "format --check"
+
+  py_linting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # passing ruff linting is required
+      - name: Python - Check Linting - ruff
+        uses: astral-sh/ruff-action@v1
+
+      # passing pylint is not required - discuss errors in code review
+      # adapted from https://github.com/davidslusser/actions_python_pylint/tree/main
+      - name: python version
+        run: python --version
+        shell: bash
+        if: always()
+      - name: install pylint
+        run: |
+          python -  m pip install --upgrade pip
+          pip install pylint
+        shell: bash
+      - name: Python - Check Linting - pylint
+        run: "pylint solutions tests  || echo '::warning title=Pylint Error(s)::Discuss solutions and trade-offs in code review.'"
+        shell: bash
+
+  py_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: python version
+        run: python --version
+        shell: bash
+
+      - name: Check for test files
+        id: check_tests
+        run: |
+          test_files=$(find ./solutions/tests -type f -name "test_*.py")
+          if [ -n "$test_files" ]; then
+            echo "Found test files:"
+            echo "$test_files"
+            echo "has_tests=true" >> $GITHUB_OUTPUT
+          else
+            echo "No test files found matching pattern ./solutions/tests/test_*.py"
+            echo "has_tests=false" >> $GITHUB_OUTPUT
+          fi
+        shell: bash
+
+      - name: Python - Run Tests
+        if: steps.check_tests.outputs.has_tests == 'true'
+        run: python -m unittest
+        shell: bash

.gitignore

@@ -0,0 +1,7 @@
+__pycache__
+*.pytest_cache
+venv/
+# .env
+*.db
+*.idea
+*.ruff_cache

.ls-lint.yml

@@ -0,0 +1,17 @@
+ls:
+  .dir: snake_case
+  .*: snake_case
+  .md: snake_case | regex:[0-9A-Z\-]+
+  .txt: snake_case | kebab-case
+  .yml: snake_case | kebab-case
+
+ignore:
+  - .git
+  - .github
+  - .vscode
+  - venv
+  - .ruff_cache
+  - .pytest_cache
+  - __pycache__
+  - .ls-lint.yml
+  - .markdownlint.yml

.markdownlint.yml

@@ -0,0 +1,3 @@
+ignore:
+  - venv
+  - .github

.vscode/extensions.json

@@ -0,0 +1,51 @@
+{
+    "recommendations": [
+        // For Pair Programming
+        "MS-vsliveshare.vsliveshare",
+
+        // For Git & GitHub
+        "mhutchie.git-graph",
+        "eamodio.gitlens",
+        "GitHub.vscode-pull-request-github",
+        "donjayamanne.githistory",
+
+        // For programming generally
+        "streetsidesoftware.code-spell-checker",
+        "leodevbro.blockman",
+        "alefragnani.project-manager",
+        "vscode-icons-team.vscode-icons",
+        "alefragnani.bookmarks",
+        "visualstudioexptteam.vscodeintellicode",
+        "aaron-bond.better-comments",
+        "christian-kohler.path-intellisense",
+        "usernamehw.errorlens",
+        "tamasfe.even-better-toml",
+
+        // For writing Markdown
+        "DavidAnson.vscode-markdownlint",
+        "yzhang.markdown-all-in-one",
+        "bierner.markdown-preview-github-styles",
+
+        // For writing Python
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "KevinRose.vsc-python-indent",
+        "njpwerner.autodocstring",
+        "LittleFoxTeam.vscode-python-test-adapter",
+        "ms-python.black-formatter",
+        "charliermarsh.ruff",
+        "ms-python.pylint",
+        "oderwat.indent-rainbow",
+        "ms-python.debugpy",
+        "frhtylcn.pythonsnippets",
+
+        // For writing Notebooks
+        "ms-toolsai.jupyter",
+        "ms-toolsai.jupyter-keymap",
+
+        // For working with data
+        "RandomFractalsInc.vscode-data-preview",
+        "mechatroner.rainbow-csv",
+        "mtxr.sqltools"
+    ]
+}