use pyproject_ops folder structure

.github/workflows/main.yml

@@ -6,9 +6,9 @@ name: CI
 
 on:
   push: # any push event to master will trigger this
-    branches: ["master"]
+    branches: ["master", "dev"]
   pull_request: # any pull request to master will trigger this
-    branches: ["master"]
+    branches: ["master", "dev"]
   workflow_dispatch: # allows you to manually trigger run
 
 jobs:

.readthedocs.yml

@@ -0,0 +1,18 @@
+# Ref: https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+  - method: pip
+    path: .
+  - requirements: requirements.txt
+  - requirements: requirements-doc.txt
+  - requirements: requirements-furo-sphinx-search.txt

AUTHORS.rst

@@ -2,15 +2,14 @@
 
 About the Author
 ------------------------------------------------------------------------------
-
 ::
 
    (\ (\
-   ( -.-)o    I am a lovely Rabbit!
+   ( -.-)o
    o_(")(")
 
-**Sanhe Hu** is a very active **Python Developer** Since 2010. Research area includes **Machine Learning, Big Data Infrastructure, Block Chain, Business Intelligent, AWS, Distributive System**. Love photography, outdoor, arts, game, and also the best `Python <https://www.python.org/>`_.
+**Sanhe Hu** is a seasoned software engineer with a deep passion for Python development since 2010. As an author and maintainer of 20+ open-source projects, I bring a wealth of experience to the table. As a Senior Solution Architect and Subject Matter Expert in Amazon Web Services, Cloud Engineering, DevOps, Big Data, and Machine Learning, I thrive on helping clients with platform design, enterprise architecture, and strategic roadmaps.
+
+Talk is cheap, show me the code:
 
 - My Github: https://github.com/MacHu-GWU
-- My HomePage: http://www.sanhehu.org/
-- My Linkedin: https://www.linkedin.com/in/sanhehu/

MANIFEST.in

@@ -1,2 +1,10 @@
-include README.rst LICENSE.txt requirements.txt release-history.rst
-recursive-include pathlib_mate *.*
+# A MANIFEST.in file can be added in a project to define the list of files
+# to include in the distribution built by the sdist command.
+#
+# For more info: https://docs.python.org/2/distutils/sourcedist.html#manifest-related-options
+
+recursive-include pathlib_mate
+include *.txt
+include *.rst
+exclude *.pyc
+exclude *.pyo

pathlib_mate/docs/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+doc_data = dict()

pathlib_mate/tests/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+from .helper import run_cov_test

pathlib_mate/tests/helper.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+from ..paths import dir_project_root, dir_htmlcov
+from ..vendor.pytest_cov_helper import run_cov_test as _run_cov_test
+
+
+def run_cov_test(
+    script: str, module: str, preview: bool = False, is_folder: bool = False
+):
+    _run_cov_test(
+        script=script,
+        module=module,
+        root_dir=f"{dir_project_root}",
+        htmlcov_dir=f"{dir_htmlcov}",
+        preview=preview,
+        is_folder=is_folder,
+    )

pathlib_mate/vendor/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+

pathlib_mate/vendor/pytest_cov_helper.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+import contextlib
+import subprocess
+from pathlib import Path
+
+
+@contextlib.contextmanager
+def temp_cwd(path: Path):
+    """
+    Temporarily set the current working directory (CWD) and automatically
+    switch back when it's done.
+    """
+    cwd = os.getcwd()
+    os.chdir(str(path))
+    try:
+        yield path
+    finally:
+        os.chdir(cwd)
+
+
+def run_cov_test(
+    script: str,
+    module: str,
+    root_dir: str,
+    htmlcov_dir: str,
+    preview: bool = False,
+    is_folder: bool = False,
+):
+    """
+    The pytest-cov plugin gives you the coverage for entire project. What if
+    I want run per-module test independently and get per-module coverage?
+
+    This is a simple wrapper around pytest + coverage cli command. Allow you to run
+    coverage test from Python script and set the code coverage measurement scope.
+
+    Usage example:
+
+    suppose you have a source code folder structure like this::
+
+        /dir_git_repo/
+        /dir_git_repo/my_library
+        /dir_git_repo/my_library/__init__.py
+        /dir_git_repo/my_library/module1.py
+        /dir_git_repo/my_library/module2.py
+
+    In your module 1 unit test script, you can do this:
+
+    .. code-block:: python
+
+        from my_library.module1 import func1, func2
+
+        def test_func1():
+            pass
+
+        def test_func2():
+            pass
+
+        if __name__ == "__main__":
+            from fixa.pytest_cov_helper import run_cov_test
+
+            run_cov_test(
+                script=__file__,
+                module="my_library.module1", # test scope is the module1.py
+                root_dir="/path/to/dir_git_repo",
+                htmlcov_dir="/path/to/dir_git_repo/htmlcov",
+            )
+
+    In your all modules unit test script, you can do this:
+
+    .. code-block:: python
+
+        if __name__ == "__main__":
+            from fixa.pytest_cov_helper import run_cov_test
+
+            run_cov_test(
+                script=__file__,
+                module="my_library", # test scope is the my_library/
+                root_dir="/path/to/dir_git_repo",
+                htmlcov_dir="/path/to/dir_git_repo/htmlcov",
+                is_folder=True, # my_library is a folder
+            )
+
+    :param script: the path to test script
+    :param module: the dot notation to the python module you want to calculate
+        coverage
+    :param root_dir: the dir to dump coverage results binary file
+    :param htmlcov_dir: the dir to dump HTML output
+    :param preview: whether to open the HTML output in web browser after the test
+    :param is_folder: whether the module is a folder
+
+    Reference:
+
+    - https://pypi.org/project/pytest-cov/
+    """
+    bin_pytest = Path(sys.executable).parent / "pytest"
+    if is_folder:
+        script = f"{Path(script).parent}"
+    if module.endswith(".py"):  # pragma: no cover
+        module = module[:-3]
+    args = [
+        f"{bin_pytest}",
+        "-s",
+        "--tb=native",
+        f"--rootdir={root_dir}",
+        f"--cov={module}",
+        "--cov-report",
+        "term-missing",
+        "--cov-report",
+        f"html:{htmlcov_dir}",
+        script,
+    ]
+    with temp_cwd(Path(root_dir)):
+        subprocess.run(args)
+    if preview:  # pragma: no cover
+        platform = sys.platform
+        if platform in ["win32", "cygwin"]:
+            open_command = "start"
+        elif platform in ["darwin", "linux"]:
+            open_command = "open"
+        else:
+            raise NotImplementedError
+        subprocess.run([open_command, f"{Path(htmlcov_dir).joinpath('index.html')}"])

pyproject_ops.json

@@ -0,0 +1,18 @@
+{
+    // the python package name, use lowercase, digits, and underscore only
+    // this would be the name for ``pip install ${package_name}``
+    "package_name": "pathlib_mate",
+    // the python major version you use for local development
+    "dev_py_ver_major": 3,
+    // the python minor version you use for local development
+    "dev_py_ver_minor": 8,
+    // the python micro version you use for local development
+    "dev_py_ver_micro": 11,
+
+    // if you use AWS S3 to host your document website
+    // it is the aws profile you use for doc site deployment
+    // leave empty string "" if you don't use it
+    "doc_host_aws_profile": "",
+    // it is the aws s3 bucket you use to store you document files
+    "doc_host_s3_bucket": ""
+}

requirements-automation.txt

@@ -0,0 +1 @@
+# This requirements file should only include dependencies for automation, shell scripts, cli, etc ...

requirements-dev.txt

@@ -1,2 +1,5 @@
-twine>=1.13.0                   # make distribution archive
-wheel>=0.33.1                   # make pre-compiled distribution package
+# This requirements file should only include dependencies for development
+pathlib_mate                            # autopep8 your code
+twine                                   # make distribution archive
+wheel                                   # make pre-compiled distribution package
+build                                   # build distribution package

requirements-doc.txt

@@ -1,15 +1,24 @@
 # This requirements file should only include dependencies for documentations
-# sphinx doc builder
-sphinx==4.3.0
-
-# Extensions
-sphinx-inline-tabs==2021.8.17b10        # allow inline tab
-sphinx-jinja==1.1.1                     # allow jinja2 template
-sphinx-copybutton==0.4.0                # add copy to clipboard button for code block
-rstobj==0.0.7                           # generate list table from data
-
-# docfly                                # auto API manual, auto Table of Content
-docfly==1.0.2                           # sphinx-doc automation
-
-# Theme
-furo==2021.8.31                         # modern doc theme
+Sphinx==5.3.0
+# enable jinja syntax in reStructuredText
+sphinx-jinja==2.0.2
+# add copy button to code block
+sphinx-copybutton==0.5.1
+# add additional design pattern to sphinx
+sphinx-design==0.5.0
+# the sphinx theme
+furo==2023.03.27
+# add jupyter notebook in sphinx doc
+nbsphinx==0.8.12
+# generate reStructuredText in Python
+rstobj==1.2.1
+# syntax highlight
+pygments==2.15.1
+# iPython
+ipython==8.10.0
+# automaticall generate .. toctree directives and API reference doc
+docfly==2.0.1
+# note: for furo-sphinx-search (https://github.com/harshil21/furo-sphinx-search)
+# you have to manually do ``pip install -r requirements-furo-sphinx-search.txt``
+# note: you need to install awscli to upload the documentation website to S3
+# awscli has werid dependency issue, so we install it out side of poetry

requirements-furo-sphinx-search.txt

@@ -0,0 +1,2 @@
+# enable readthedocs sphinx search for furo theme
+furo-sphinx-search @ git+https://github.com/MacHu-GWU/furo-sphinx-search@main

requirements-test.txt

@@ -1,5 +1,3 @@
-# dependencies for test
-pytest # prefer 5.4.3
-pytest-cov # prefer 2.10.1
-tox
-autopep8
+# This requirements file should only include dependencies for testing
+pytest                                  # test framework
+pytest-cov                              # coverage test