chore(build): setup project

Set up the following project items:

- Linters
- Tests
- Coverage Reporting
- Docs
- CI Workflows
- Pre-Commit Hooks

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on: [push]
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+ build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up project using python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    # Run all pre-commit hooks on all the files.
+    # Getting only staged files can be tricky in case a new PR is opened
+    # since the action is run on a branch in detached head state
+    - name: Install and run pre-commit
+      uses: pre-commit/action@v3.0.0
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install tox tox-gh-actions
+
+    - name: Test with tox
+      run: tox -r

.gitignore

@@ -303,6 +303,7 @@ tags
 
 ### Project template
 dist/*
+docs/api
 .pytest_cache/
 .ipython/
 .env

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+      - id: check-toml
+      - id: check-vcs-permalinks
+      - id: check-yaml
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: "v0.0.287"
+    hooks:
+      - id: ruff
+        args: [ --fix, --exit-non-zero-on-fix ]
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.10.1
+    hooks:
+      - id: pyupgrade
+        args: ["--py310-plus"]
+
+# sets up .pre-commit-ci.yaml to ensure pre-commit dependencies stay up to date
+ci:
+  autoupdate_schedule: weekly
+  skip: []
+  submodules: false

README.md

@@ -1,12 +1,30 @@
 # SGHI Commons
 
+[![pyversion](https://camo.githubusercontent.com/64bafa7ada773716674e93fd8fbaa3f681e1748865cdcb47cc373579079b767f/68747470733a2f2f696d672e736869656c64732e696f2f707970692f707976657273696f6e732f7365747570746f6f6c732e737667)](https://camo.githubusercontent.com/64bafa7ada773716674e93fd8fbaa3f681e1748865cdcb47cc373579079b767f/68747470733a2f2f696d672e736869656c64732e696f2f707970692f707976657273696f6e732f7365747570746f6f6c732e737667)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+
 A collection of utilities and reusable components used throughout our Python
 projects. They include:
 
 - Components for defining and accessing application configurations.
 - A registry component for storing key-value pairs.
 - A signal dispatcher inspired by [PyDispatch](https://grass.osgeo.org/grass83/manuals/libpython/pydispatch.html) and [Django Dispatch](https://docs.djangoproject.com/en/dev/topics/signals/).
 
+## Contribute
+
+Clone the project and run the following command to install dependencies:
+
+```bash
+pip install -e .[dev,test,docs]
+```
+
+Set up pre-commit hooks:
+```bash
+pre-commit install
+```
+
 ## License
 
 [MIT License](https://github.com/savannahghi/sghi-commons/blob/main/LICENSE)

docs/conf.py

@@ -0,0 +1,175 @@
+# ruff: noqa
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("src"))
+
+
+# -----------------------------------------------------------------------------
+# Project information
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+# -----------------------------------------------------------------------------
+
+author = "Savannah Global Health Institute"
+copyright = "2023, Savannah Global Health Institute"
+project = "sghi-commons"
+
+
+# -----------------------------------------------------------------------------
+# General configuration
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+# -----------------------------------------------------------------------------
+
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary"]
+
+# Preserve authored syntax for defaults
+autodoc_preserve_defaults = True
+
+autodoc_default_flags = {
+    "inherited-members": True,
+    "show-inheritance": True,
+    "special-members": (
+        "__enter__",
+        "__exit__",
+        "__call__",
+        "__getattr__",
+        "__setattr_",
+    ),
+}
+
+autodoc_member_order = 'groupwise'
+
+autoapi_python_use_implicit_namespaces = True
+
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+
+exclude_patterns = []
+
+# Be strict about any broken references
+nitpicky = True
+
+nitpick_ignore = [
+    ("py:class", "concurrent.futures._base.Executor"),  # sphinx can't find it
+    ("py:class", "concurrent.futures._base.Future"),  # sphinx can't find it
+    ("py:class", "sghi.disposable.decorators._D"),  # private type annotations
+    ("py:class", "sghi.disposable.decorators._DE"),  # private type annotations
+    ("py:class", "sghi.disposable.decorators._P"),  # private type annotations
+    ("py:class", "sghi.disposable.decorators._R"),  # private type annotations
+    ("py:class", "sghi.disposable.decorators.not_disposed._D"),  # private type annotations
+    ("py:class", "sghi.disposable.decorators.not_disposed._DE"),  # private type annotations
+    ("py:class", "sghi.disposable.decorators.not_disposed._P"),  # private type annotations
+    ("py:class", "sghi.disposable.decorators.not_disposed._R"),  # private type annotations
+    ("py:class", "sghi.task.task._IT"),  # private type annotations
+    ("py:class", "sghi.task.task._OT"),  # private type annotations
+    ("py:class", "sghi.task.common._IT"),  # private type annotations
+    ("py:class", "sghi.task.common._OT"),  # private type annotations
+    ("py:class", "sghi.task.concurrent._IT"),  # private type annotations
+    ("py:class", "sghi.task.concurrent._OT"),  # private type annotations
+    ("py:class", "sghi.utils.checkers._Comparable"),  # private type annotations
+    ("py:class", "sghi.utils.checkers._S"),  # private type annotations
+    ("py:class", "sghi.utils.checkers._T"),  # private type annotations
+    ("py:obj", "sghi.disposable.decorators.not_disposed._P"),  # private type annotations
+    ("py:obj", "sghi.disposable.decorators.not_disposed._R"),  # private type annotations
+    ("py:obj", "sghi.task.task._IT"),  # private type annotations
+    ("py:obj", "sghi.task.task._OT"),  # private type annotations
+    ("py:obj", "sghi.task.common._IT"),  # private type annotations
+    ("py:obj", "sghi.task.common._OT"),  # private type annotations
+    ("py:obj", "sghi.task.concurrent._IT"),  # private type annotations
+    ("py:obj", "sghi.task.concurrent._OT"),  # private type annotations
+]
+
+templates_path = ["templates"]
+
+root_doc = "index"
+
+
+# -----------------------------------------------------------------------------
+# Options for HTML output
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+# -----------------------------------------------------------------------------
+
+html_logo = "images/sghi_globe.png"
+
+html_static_path = ["static"]
+
+html_theme = "furo"
+
+html_theme_options = {
+    "sidebar_hide_name": True,
+    "light_css_variables": {
+        "color-brand-primary": "#0474AC",  # "blue"
+        "color-brand-content": "#0474AC",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#C1368C",  # "purple"
+        "color-brand-content": "#C1368C",
+    },
+}
+
+
+# -----------------------------------------------------------------------------
+# Include Python intersphinx mapping to prevent failures
+# jaraco/skeleton#51
+# -----------------------------------------------------------------------------
+
+extensions += ["sphinx.ext.intersphinx"]
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pypackage": ("https://packaging.python.org/en/latest/", None),
+    "importlib-resources": (
+        "https://importlib-resources.readthedocs.io/en/latest",
+        None,
+    ),
+    "django": (
+        "http://docs.djangoproject.com/en/dev/",
+        "http://docs.djangoproject.com/en/dev/_objects/"
+    ),
+}
+
+
+# -----------------------------------------------------------------------------
+# Support tooltips on references
+# -----------------------------------------------------------------------------
+
+extensions += ["hoverxref.extension"]
+hoverxref_auto_ref = True
+hoverxref_intersphinx = [
+    "python",
+    "pip",
+    "pypackage",
+    "importlib-resources",
+    "django",
+]
+
+
+# -----------------------------------------------------------------------------
+# Add support for nice Not Found 404 pages
+# -----------------------------------------------------------------------------
+
+extensions += ["notfound.extension"]
+
+
+# -----------------------------------------------------------------------------
+# Add icons (aka "favicons") to documentation
+# -----------------------------------------------------------------------------
+
+extensions += ["sphinx_favicon"]
+html_static_path += ["images"]  # should contain the folder with icons
+
+# List of dicts with <link> HTML attributes
+# static-file points to files in the html_static_path (href is computed)
+
+favicons = [
+    {
+        "rel": "icon",
+        "type": "image/png",
+        "static-file": "sghi_globe.png",
+        "sizes": "any",
+    },
+]

docs/index.rst

@@ -0,0 +1,48 @@
+.. sghi-commons documentation master file, created by
+   sphinx-quickstart on Thu Aug 3 01:28:14 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. image:: images/sghi_logo.webp
+   :align: center
+
+SGHI Commons
+============
+
+sghi-commons is a collection of reusable components and utilities used
+throughout `SavannahGHI Python projects <sghi_github_py_projects_>`_.
+They include utilities such as:
+
+- Components for defining and accessing application configurations.
+- A registry component for storing key-value pairs.
+- A signal dispatcher inspired by `PyDispatch <https://grass.osgeo.org/grass83/manuals/libpython/pydispatch.html>`_ and `Django Dispatch <https://docs.djangoproject.com/en/dev/topics/signals/>`_.
+
+Installation
+------------
+
+We recommend using the latest version of Python. Python 3.10 and newer is
+supported. We also recommend using a `virtual environment`_ in order
+to isolate your project dependencies from other projects and the system.
+
+Install the latest sghi-commons version using pip:
+
+.. code-block:: bash
+
+    pip install sghi-commons
+
+
+API Reference
+-------------
+
+.. autosummary::
+   :template: module.rst
+   :toctree: api
+   :caption: API
+   :recursive:
+
+     sghi.app
+     sghi.exceptions
+
+
+.. _sghi_github_py_projects: https://github.com/savannahghi/?q=&type=all&language=python&sort=
+.. _virtual environment: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments

docs/templates/class.rst

@@ -0,0 +1,45 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :special-members: __contains__, __delitem__, __enter__, __exit__, __call__, __getattr__, __setattr__, __getitem__, __setitem__
+   :show-inheritance:
+   :inherited-members:
+   :member-order: groupwise
+
+   {% if methods or attributes %}
+   ----
+   {% endif %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% if methods or attributes %}
+   ----
+   {% endif %}
+
+   {% block constructor %}
+   .. automethod:: __init__
+   {% endblock %}