feat: Initial project scaffold

.coveragerc

@@ -0,0 +1,15 @@
+[run]
+branch = True
+parallel = True
+
+omit =
+    */__init__.py
+
+[report]
+show_missing = True
+
+[html]
+directory = htmlcov
+
+[xml]
+output = xmlcov/coverage.xml

.flake8

@@ -0,0 +1,60 @@
+# flake8 plugins: https://github.com/DmytroLitvinov/awesome-flake8-extensions
+# TODO(amir): add flake8-annotations once the API refactor is completed
+# TODO(amir): add flake8-annotations-coverage
+# TODO(amir): investigate flake8-annotations-complexity
+# TODO(amir): add docstring-convention = numpydoc once API refactor is done
+# TODO(amir): investigate the tim to roll out https://peps.python.org/pep-0585/
+# https://stackoverflow.com/questions/66738753/python-typing-deprecation
+# TODO(amir): investigate https://peps.python.org/pep-0563/
+[flake8]
+max-line-length = 100
+
+ignore = 
+    # TODO(amir): E501 would ignore `max-line-length = 100` rule; we have cases that max-line-length
+    # are > 100 which is mostly comments and some front-end codes in the code base
+    # E501: Line too long
+    E501,
+    # E203: Whitespace before ':'
+    E203,
+    # E402: Module level import not at top of file
+    E402,
+    # W503: Line break occurred before a binary operator
+    W503
+    # ANN002: Missing type annotation for *args
+    ANN002,
+    # ANN003: Missing type annotation for **kwargs
+    ANN003,
+    # ANN101: Missing type annotation for self in method
+    ANN101,
+    # ANN102: Missing type annotation for cls in classmethod
+    ANN102,
+    # ANN202: Missing return type annotation for protected function
+    ANN202,
+    # ANN203: Missing return type annotation for secret function
+    ANN203,
+    # ANN204: Missing return type annotation for special method
+    ANN204,
+    # ANN401: Dynamically typed expressions (typing.Any) are disallowed.
+    ANN401,
+    # E800: Commented out code
+    E800
+
+exclude =
+    .coverage
+    .ipynb_checkpoints
+    .git,
+    .github
+    .mypy_cache,
+    .pytest_cache,
+    .python-version,
+    .tox,
+    .venv/*,
+    .vscode
+    __pycache__,
+    build,
+    dist,
+    docs/*,
+    htmlcov/*,
+    xmlcov/*,
+
+

.github/codecov.yml

@@ -0,0 +1,7 @@
+codecov:
+  branch: master
+
+coverage:
+  range: 50..90
+  round: down
+  precision: 2

.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+####################################################################################################
+# Continuous Integration [Lint, Test, Build] on All Pull-Requests + Push to Master
+####################################################################################################
+# References:
+# - https://github.com/snok/install-poetry
+# - https://github.com/actions/setup-python#caching-packages-dependencies
+# - https://stackoverflow.com/questions/62977821/how-to-cache-poetry-install-for-github-actions
+# - https://github.com/codecov/codecov-action
+####################################################################################################
+name: build
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+
+jobs:
+  ci:
+    #----------------------------------------------
+    # -----  setup operating system (os)  -----
+    #----------------------------------------------
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # TODO(amir): add "windows-latest"
+        os: ["ubuntu-latest", "macos-latest"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      #----------------------------------------------
+      # ----- check-out repo and set-up python -----
+      #----------------------------------------------
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+      - name: Setup Python v${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      #----------------------------------------------
+      # -----  install & configure poetry  -----
+      #----------------------------------------------
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+      #----------------------------------------------
+      #  -----  load cached dependencies  -----
+      #----------------------------------------------
+      # - name: Load Cached venv
+      #   id: cached-poetry-dependencies
+      #   uses: actions/cache@v3
+      #   with:
+      #     path: .venv
+      #     key: venv-${{ runner.os }}-v${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+      #----------------------------------------------
+      #  -----  install dependencies  -----
+      #----------------------------------------------
+      - name: Install Dependencies
+        run: poetry install -vv
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+      #----------------------------------------------
+      #  -----  Integration test suite  -----
+      #----------------------------------------------
+      # TODO(amir): de-dup the `source .venv/bin/activate` (`source $VENV`) command
+      - name: Lint
+        run: |
+          source $VENV
+          poe check
+      - name: Test
+        run: |
+          source $VENV
+          poe test
+      - name: Build
+        run: |
+          source $VENV
+          poetry build
+      #----------------------------------------------
+      #  ---  Upload test coverage to Codecov  ---
+      #----------------------------------------------
+      - name: Codecov
+        # NOTE: only run code coverage with one Python Version and OS; the rest is not needed
+        if: ${{ matrix.python-version == '3.9' && matrix.os == 'macos-latest' }}
+        uses: codecov/[email protected]
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          directory: ./xmlcov/
+          fail_ci_if_error: true
+          files: ./xmlcov/coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          verbose: true