mots: create initial prototype (bug 1733956)

.circleci/config.yml

@@ -0,0 +1,51 @@
+version: 2.1
+
+workflows:
+  version: 2
+  test:
+    jobs:
+      - test_3_10
+      - test_3_9
+      - test_3_8
+      - test_3_7
+
+jobs:
+  test_3_7: &test_template
+    docker:
+      - image: circleci/python:3.7
+    steps:
+      - checkout
+      - run:
+          name: setup
+          command: |
+            set -e
+            sudo apt-get install python3-venv
+            mkdir -p /tmp/test-reports
+            make dev-env
+            source .mots-env/bin/activate
+            make dev
+      - run:
+          name: run tests
+          command: |
+            set -e
+            source .mots-env/bin/activate
+            ulimit -c unlimited
+            for F in tests/test_*.py; do
+              pytest --junitxml=/tmp/test-reports/junit-$( basename $F .py ).xml -vv $F
+            done
+      - store_test_results:
+          path: /tmp/test-reports
+      - store_artifacts:
+          path: /tmo/test-reports
+  test_3_8:
+    <<: *test_template
+    docker:
+        - image: circleci/python:3.8
+  test_3_9:
+    <<: *test_template
+    docker:
+        - image: circleci/python:3.9
+  test_3_10:
+    <<: *test_template
+    docker:
+        - image: circleci/python:3.10

.coveragerc

@@ -0,0 +1,2 @@
+[run]
+source = src/mots

.flake8

@@ -0,0 +1,14 @@
+[flake8]
+# Matching black's default
+max-line-length = 88
+
+extend-ignore =
+    D107,  # Missing docstring in __init__
+
+per-file-ignores = 
+    # D100 Missing docstring in public module
+    # D101 Missing docstring in public class
+    # D102 Missing docstring in public method
+    # D103 Missing docstring in public function
+    # D104 Missing docstring in public package
+    tests/*: D100,D101,D102,D103,D104

.gitignore

@@ -6,5 +6,3 @@ __pycache__
 dist/
 documentation/_build
 htmlcov/
-mots.log
-notes

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+   configuration: documentation/conf.py
+
+python:
+   install:
+   - requirements: requirements.txt

AUTHORS

@@ -0,0 +1 @@
+Zeid Zabaneh <zeid@mozilla.com>

CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+# Community Participation Guidelines
+
+This repository is governed by Mozilla's code of conduct and etiquette guidelines. 
+For more details, please read the
+[Mozilla Community Participation Guidelines](https://www.mozilla.org/about/governance/policies/participation/). 
+
+## How to Report
+For more information on how to report violations of the Community Participation Guidelines, please read our '[How to Report](https://www.mozilla.org/about/governance/policies/participation/reporting/)' page.

Makefile

@@ -0,0 +1,109 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+SHELL := /bin/bash
+PYTHON := $(shell which python)
+
+
+.PHONY: help
+help:
+	@echo "using python at $(PYTHON)."
+	@$(PYTHON) --version
+	@echo "usage: make <target>"
+	@echo
+	@echo "target is one of:"
+	@echo "    help          show this message and exit"
+	@echo "    build         build the python package and wheels"
+	@echo "    clean         remove temporary files"
+	@echo "    cov           run coverage check"
+	@echo "    cov-html      generate html coverage report"
+	@echo "    dev           setup local dev environment by installing required packages, etc."
+	@echo "    dev-env       create a python virtual environment in ./mots-env"
+	@echo "    docs          generate documentation"
+	@echo "    requirements  regenerate requirements.txt"
+	@echo "    serve-cov     simple http server for coverage report"
+	@echo "    serve-docs    simple http server for docs"
+	@echo "    test          run the test suite"
+
+.PHONY: test
+test:
+	$(PYTHON) -m pytest -vvv
+
+.PHONY: build
+build:
+	$(PYTHON) -m build
+
+.PHONY: docs
+docs:
+	make -C documentation html
+
+.PHONY: cov
+cov:
+	-@rm -R .coverage 2>/dev/null ||:
+	$(PYTHON) -m pytest --cov-fail-under=50 --cov=src/mots tests
+
+.PHONY: cov-html
+cov-html:
+	-@rm -R .coverage 2>/dev/null ||:
+	-@rm -R .htmlcov 2>/dev/null ||:
+	$(PYTHON) -m pytest --cov=src/mots tests --cov-report html
+
+.PHONY: serve-cov
+serve-cov:
+	$(PYTHON) -m http.server -d htmlcov 8080
+
+.PHONY: format
+format:
+	$(PYTHON) -m black src/mots
+	$(PYTHON) -m black tests
+	$(PYTHON) -m black documentation
+
+.PHONY: requirements
+requirements:
+	rm requirements/*.txt
+	docker-compose run generate-python3.7-requirements
+	docker-compose run generate-python3.8-requirements
+	docker-compose run generate-python3.9-requirements
+	docker-compose run generate-python3.10-requirements
+
+.ONESHELL:
+.PHONY: dev-env
+dev-env:
+ifdef PY
+	@echo "Creating virtual env in .mots-env using provided Python ($(PY))..."
+	-@(/usr/bin/$(PY) -m venv .mots-env && ([ $$? -eq 0 ] && echo "$(PY) found.")) 2>/dev/null||
+	-@(/usr/local/bin/$(PY) -m venv .mots-env && ([ $$? -eq 0 ] && echo "$(PY) found.")) 2>/dev/null
+else
+	@echo "PY variable not defined, using python3 if available..."
+	@echo "Creating virtual env in .mots-env using python3..."
+	-@(python3 -m venv .mots-env && ([ $$? -eq 0 ] && echo "Found $(shell python3 --version)")) 2>/dev/null
+endif
+
+.ONESHELL:
+.PHONY: dev
+dev:
+	deactivate
+	set -e
+	source ./.mots-env/bin/activate
+	python -m pip install --upgrade pip
+	python -m pip install pip-tools
+	python -m pip install -r requirements/$$(./requirements/get_filename)
+	python -m pip install -e .
+
+.PHONY: serve-docs
+serve-docs:
+	$(PYTHON) -m http.server -d documentation/_build/html 8080
+
+.PHONY: clean
+clean:
+	-@rm -R htmlcov 2>/dev/null ||:
+	-@rm -R documentation/_build 2>/dev/null ||:
+	-@rm -R dist 2>/dev/null ||:
+	-@rm -R src/*.egg-info 2>/dev/null ||:
+	-@rm -R src/mots/__pycache__ 2>/dev/null ||:
+	-@rm -R tests/__pycache__ 2>/dev/null ||:
+	-@rm -R .coverage 2>/dev/null ||:
+	-@rm -R .pytest_cache 2>/dev/null ||:
+	-@rm -R .mots-env 2>/dev/null ||:
+	-@rm -R .pytest_cache-env 2>/dev/null ||:

README.md

@@ -0,0 +1,25 @@
+mots - Module Ownership in Tree System
+======================================
+
+[Full documentation](https://mots.readthedocs.io/en/latest/) can be viewed online.
+
+### Contributing
+
+- All contributors must abide by the Mozilla Code of Conduct.
+
+- The [main repository](https://github.com/mozilla-conduit/mots) is hosted on GitHub. Pull requests should be submitted against the `main` branch.
+
+- Bugs are tracked [on Bugzilla](https://bugzilla.mozilla.org), under the `Conduit::mots` component.
+
+
+Development environment
+=======================
+To set up a local development environment, run the following commands. Optionally replace the python version with the desired version on your local machine.
+
+.. code-block:: bash
+
+    make dev-env PY=python3.9
+    source .mots-env/bin/activate
+    make dev
+
+The above commands will set up a local development environment using the provided python version available on your machine, and subsequently install all required packages in that environment.

docker-compose.yml

@@ -0,0 +1,23 @@
+version: '2'
+
+services:
+    generate-python3.7-requirements:
+        image: python:3.7
+        command: sh -c "cd /mots && pip install pip-tools && python -m piptools compile requirements/base.in --generate-hashes -o requirements/python3.7.txt"
+        volumes:
+            - .:/mots
+    generate-python3.8-requirements:
+        image: python:3.8
+        command: sh -c "cd /mots && pip install pip-tools && python -m piptools compile requirements/base.in --generate-hashes -o requirements/python3.8.txt"
+        volumes:
+            - .:/mots
+    generate-python3.9-requirements:
+        image: python:3.9
+        command: sh -c "cd /mots && pip install pip-tools && python -m piptools compile requirements/base.in --generate-hashes -o requirements/python3.9.txt"
+        volumes:
+            - .:/mots
+    generate-python3.10-requirements:
+        image: python:3.10
+        command: sh -c "cd /mots && pip install pip-tools && python -m piptools compile requirements/base.in --generate-hashes -o requirements/python3.10.txt"
+        volumes:
+            - .:/mots

documentation/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

documentation/conf.py

@@ -0,0 +1,58 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""Configuration file for the Sphinx documentation builder."""
+
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "mots"
+copyright = "2021 - 2022 Mozilla Inc."
+author = "Zeid Zabaneh <zeid@mozilla.com>"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]