Adds CONTRIBUTING.md

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.15
+current_version = 0.0.16
 commit = False
 tag = True
 

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.github/workflows/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+<!-- Inspired by https://github.com/burnash/gspread/blob/master/.github/CONTRIBUTING.md -->
+# Contributing Guide
+
+- Check the [GitHub Issues](https://github.com/manmartgarc/stochatreat/issues) for open issues that need attention.
+- Follow the [How to submit a contribution](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution) Guide.
+
+- Make sure unit tests pass. Please read how to run unit tests [below](#tests).
+
+- If you are fixing a bug:
+  - If you are resolving an existing issue, reference the issue ID in a commit message `(e.g., fixed #XXXX)`.
+  - If the issue has not been reported, please add a detailed description of the bug in the Pull Request (PR).
+  - Please add a regression test case to check the bug is fixed.
+
+- If you are adding a new feature:
+  - Please open a suggestion issue first.
+  - Provide a convincing reason to add this feature and have it greenlighted before working on it.
+  - Add tests to cover the functionality.
+
+- Please follow [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/).
+
+## Setting up development environment
+
+You can install the development environment, i.e. all the dependencies required to run all tests and checks that are run when you submit a PR, by running. There are two main ways of doing this, one is to do it without cloning the repository, and the other is to clone the repository and then install the dependencies.
+
+### Without cloning the repository
+
+```bash
+pip install "stochatreat[dev] @ git+https://github.com/manmartgarc/stochatreat"
+```
+
+### Cloning the repository
+
+```bash
+git clone https://github.com/manmartgarc/stochatreat
+cd stochatreat
+pip install -e .[dev]
+```
+
+## Tests
+
+To run tests run:
+
+```bash
+make test
+```
+
+## Format
+
+When submitting a PR, the CI will run `make format` and also `make lint` to check the format of the code. You can run this locally by running:
+
+```bash
+make format lint
+```
+
+## Release
+
+- Run `bump2version` to update the version number in the `setup.py` file and create a new tag:
+
+  ```bash
+  bump2version [major|minor|patch]
+  ```
+
+- Commit the changes and push them to your fork.
+- Submit a PR.
+- Once the PR is merged, run `make release` to create a new release in GitHub.

.github/workflows/test.yml

@@ -30,9 +30,9 @@ jobs:
       - name: Lint with Ruff
         run: |
           make lint
-      - name: Check style with Black
+      - name: Check format with Black
         run: |
-          make style
+          make format
       - name: Type-checking with Mypy
         run: |
           make test/mypy

Makefile

@@ -1,49 +1,55 @@
 .DEFAULT_GOAL := all
 
-all: clean lint style test dist
+# taken from here: https://dwmkerr.com/makefile-help-command/
+.PHONY: help
+help: # Show help for each of the Makefile recipes
+	@grep -E '^[a-zA-Z0-9 -]+:.*#'  Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
 
-clean: clean-build clean-pyc clean-test
 
-clean-build:
+all: clean lint format test dist # Runs all recipes.
+
+clean: clean-build clean-pyc clean-test # Runs all clean recipes.
+
+clean-build: # Cleans all build files.
 	rm -fr build/
 	rm -fr dist/
 	rm -fr .eggs/
 	find . -name '*.egg-info' -exec rm -fr {} +
 	find . -name '*.egg' -exec rm -f {} +
 
-clean-pyc:
+clean-pyc: # Cleans all python cache files.
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
 	find . -name '*~' -exec rm -f {} +
 	find . -name '__pycache__' -exec rm -fr {} +
 
-clean-test:
+clean-test: # Cleans all test files.
 	rm -fr .tox/
 	rm -f .coverage
 	rm -fr htmlcov/
 	rm -fr .pytest_cache
 
-dist: clean
+dist: clean # Builds source and wheel package.
 	python -m build
 	ls -lth dist/
 
-lint: lint/ruff
+lint: lint/ruff # Runs all linting.
 
-lint/ruff:
+lint/ruff: # Runs ruff linting.
 	ruff src tests
 
-release: dist
+release: dist # Releases a new version to PyPi.
 	twine upload dist/*
 
-style: style/black
+format: format/black # Runs all format checks.
 
-style/black:
+format/black: # Runs black format checks.
 	black --check src tests
 
-test: test/mypy test/pytest
+test: test/mypy test/pytest # Runs all tests.
 
-test/pytest:
+test/pytest: # Runs pytest tests.
 	pytest
 
-test/mypy:
+test/mypy: # Runs mypy tests.
 	mypy

README.md

@@ -5,7 +5,7 @@
 |Build|[![Main Branch Tests](https://github.com/manmartgarc/stochatreat/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/manmartgarc/stochatreat/actions/workflows/test.yml)
 |PyPI| [![pypi](https://img.shields.io/pypi/v/stochatreat?logo=pypi)](https://pypi.org/project/stochatreat/) ![pypi-downloads](https://img.shields.io/pypi/dm/stochatreat?logo=pypi)
 |conda-forge| [![Conda](https://img.shields.io/conda/v/conda-forge/stochatreat?logo=conda-forge)](https://anaconda.org/conda-forge/stochatreat) ![conda-downloads](https://img.shields.io/conda/dn/conda-forge/stochatreat?logo=conda-forge)
-|Meta| [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/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) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/)
+|Meta| [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code format - Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/)
 
 ---
 
@@ -119,6 +119,10 @@ nhood dummy
       1      35  68
 ```
 
+## Contributing
+
+If you'd like to contribute to the package, make sure you read the [contributing guide](https://github.com/manmartgarc/stochatreat/blob/main/.github/CONTRIBUTING.md).
+
 ## References
 
 - `stochatreat` is totally inspired by [Alvaro Carril's](https://acarril.github.io/) fantastic STATA package: [`randtreat`](https://acarril.github.io/posts/randtreat), which was published in [The Stata Journal](https://www.stata-journal.com/article.html?article=st0490).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stochatreat"
-version = "0.0.15"
+version = "0.0.16"
 description = 'Stratified random assignment using pandas'
 readme = "README.md"
 requires-python = ">=3.8"
@@ -13,11 +13,9 @@ keywords = [
   "block randomization",
   "stratified randomization",
   "stratified random assignment",
-  "strata"
-]
-authors = [
-  { name = "Manuel Martinez", email = "[email protected]" },
+  "strata",
 ]
+authors = [{ name = "Manuel Martinez", email = "[email protected]" }]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Programming Language :: Python",
@@ -33,37 +31,40 @@ classifiers = [
 dependencies = ["pandas"]
 
 [project.optional-dependencies]
-dev = [
-  "black",
-  "build",
-  "bump2version",
-  "mypy",
-  "ruff",
-  "pytest",
-  "pytest-cov"
-]
+dev = ["black", "build", "bump2version", "mypy", "ruff", "pytest", "pytest-cov"]
 
 [project.urls]
 Documentation = "https://github.com/manmartgarc/stochatreat/blob/main/README.md"
 Issues = "https://github.com/manmartgarc/stochatreat/issues"
 Source = "https://github.com/manmartgarc/stochatreat/"
 
-[tools.setuptools.packages.find]
+[tool.setuptools.packages.find]
 where = ["src"]
+exclude = ["tests"]
 namespaces = false
 
+[tool.setuptools.package-data]
+stochatreat = ["py.typed"]
+
 [tool.black]
 line-length = 79
 
 [tool.mypy]
 python_version = 3.8
+files = ["src", "tests"]
+check_untyped_defs = true
+show_error_codes = true
+pretty = true
 ignore_missing_imports = true
-packages = ["src"]
+
+[tool.ruff]
+line-length = 79
+target-version = "py38"
 
 [tool.pytest.ini_options]
 addopts = [
   "--cov=stochatreat",
   "--cov-branch",
   "--cov-report=term-missing",
-  "--durations=5"
-]
+  "--durations=5",
+]

tests/test_stochatreat_io.py

@@ -59,7 +59,7 @@ def test_input_empty_data(correct_params):
     with pytest.raises(ValueError):
         stochatreat(
             data=empty_data,
-            stratum_cols="stratum",
+            stratum_cols=["stratum"],
             treats=correct_params["treat"],
             idx_col=correct_params["idx_col"],
             probs=correct_params["probs"],
@@ -77,7 +77,7 @@ def test_input_idx_col_str(correct_params):
             data=correct_params["data"],
             stratum_cols=["stratum"],
             treats=correct_params["treat"],
-            idx_col=idx_col_not_str,
+            idx_col=idx_col_not_str,  # type: ignore
             probs=correct_params["probs"],
         )
 
@@ -317,7 +317,7 @@ def test_output_index_and_idx_col_correspondence(
 
     treatments = stochatreat(
         data=data_with_rand_index,
-        stratum_cols="stratum",
+        stratum_cols=["stratum"],
         probs=probs,
         treats=2,
         idx_col=idx_col,