From b08743073bd443be73aeac99d63fae50566eb953 Mon Sep 17 00:00:00 2001 From: Ryan McGinty Date: Mon, 2 Dec 2024 14:53:51 -0800 Subject: [PATCH] Adding initial license and docs --- .github/workflows/release.yml | 65 +++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 29 ++++++++++++++++ LICENSE | 33 ++++++++++++++++++ Makefile | 5 +++ README.md | 59 ++++++++++++++++++++++++++++++- pyproject.toml | 29 +++++++++++----- 6 files changed, 210 insertions(+), 10 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..0691aa4 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,65 @@ +name: Publish to PyPI + +on: + workflow_dispatch: + inputs: + part: + description: "Semver part to bump (major, minor, patch)" + type: choice + required: true + default: "patch" + options: ["major", "minor", "patch"] + dry-run: + description: "Dry run" + type: boolean + required: true + default: true + +jobs: + + build: + name: Build distribution + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python-version: ["3.9", "3.10", "3.11", "3.12"] + steps: + - uses: actions/checkout@v4 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + - name: Set up AllenInstitute Repo Authorization + uses: ./.github/actions/setup-ai-github-urls + with: + token: ${{ secrets.AI_PACKAGES_TOKEN }} + - name: Run Release + run: | + make dist + shell: bash + - name: Store the distribution packages + uses: actions/upload-artifact@v4 + with: + name: python-package-distributions + path: dist/ + + publish-to-pypi: + name: Publish to PyPI + needs: build + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/aibs-informatics-test-resources + permissions: + id-token: write # IMPORTANT: mandatory for trusted publishing + steps: + - name: Download all the dists + uses: actions/download-artifact@v4 + with: + name: python-package-distributions + path: dist/ + - name: Publish distribution to PyPI + if: ${{ github.event.inputs.dry-run == 'false' }} + uses: pypa/gh-action-pypi-publish@release/v1 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..afd78bc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,29 @@ +# Contributing to `aibs-informatics-test-resources` + +Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. + +## Types of Contributions + +### Reporting Bugs + +Report bugs to our [issues page](https://github.com/aibs-informatics-test-resources/issues). + +If you are reporting a bug, please include: + +- Your operating system name and version. +- Any details about your local setup that might be helpful in troubleshooting. +- Detailed steps to reproduce the bug, in the form of a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example). + +### Making Changes + +Look through the GitHub issues for bugs, features, and other requests. Most issues will have a label that can help you identify the type of issue. + +### Submitting Feedback + +The best way to send feedback is to [create an issue](https://github.com/aibs-informatics-test-resources/issues/new) on GitHub. + +If you are proposing a feature: + +- Explain in detail how it would work. +- Keep the scope as narrow as possible, to make it easier to implement. +- Remember that while contributions are welcome, developer/maintainer time is limited. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..89605f8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,33 @@ +Allen Institute Software License – This software license is the 2-clause BSD +license plus a third clause that prohibits redistribution and use for +commercial purposes without further permission. + +Copyright © 2024. Allen Institute. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this +list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, +this list of conditions and the following disclaimer in the documentation +and/or other materials provided with the distribution. + +3. Redistributions and use for commercial purposes are not permitted without +the Allen Institute’s written permission. For purposes of this license, +commercial purposes are the incorporation of the Allen Institute's software +into anything for which you will charge fees or other compensation or use of +the software to perform a commercial service for a third party. Contact +terms@alleninstitute.org for commercial licensing opportunities. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/Makefile b/Makefile index fdde6f8..a4d9752 100644 --- a/Makefile +++ b/Makefile @@ -166,6 +166,11 @@ coverage-server: $(INSTALL_STAMP) ## Run coverage server ##@ Release Commands ##################### +dist: $(PYTHON) $(DEP_FILES) ## Build source and wheel package + @. $(VENV_BIN)/activate;\ + $(PIP) install .[release];\ + $(PYTHON) -m build; + reinstall: obliterate install ## Recreate environment and install pre-build: obliterate ## Removes existing build environment diff --git a/README.md b/README.md index 7728eca..bf882dd 100644 --- a/README.md +++ b/README.md @@ -4,4 +4,61 @@ --- -Python test utility package +## Overview + +This package provides a collection of utilities and resources to facilitate testing in various AIBS Informatics projects. It includes base test classes, mock utilities, and other helpful tools. + +## Available Modules + +### Base Test Class + +The [`BaseTest`](./src/aibs_informatics_test_resources/base.py) class provides a base class for creating unit tests with common setup and teardown functionality. It includes the following features: + +- **Environment Management**: + - `set_env_vars(*key_values_pairs: Tuple[str, Optional[str]])`: Set environment variables for the duration of the test. + - `reset_environ`: Class variable to reset environment variables after each test. + +- **Temporary Files and Directories**: + - `tmp_path(basename: Optional[str] = None) -> Path`: Create a temporary directory. + - `tmp_file(basename: Optional[str] = None, dirname: Optional[str] = None, content: Optional[str] = None) -> Path`: Create a temporary file with optional content. + +- **Assertions**: + - `assertStringPattern(pattern: str, actual: str)`: Assert that a string matches a given regex pattern. + - `assertJsonEqual(first: Union[dict, str, int, list], second: Union[dict, str, int, list])`: Assert that two JSON objects are equal. + - `assertListEqual(list1: List[Any], list2: List[Any], msg: Any = None, presort: bool = False, **presort_kwargs) -> None`: Assert that two lists are equal, with an option to sort them before comparison. + +- **Mocking**: + - `create_patch(name: str, **kwargs) -> MagicMock`: Create a patch for a given name and add it to the cleanup list. + +- **Context Managers**: + - `chdir(destination: Union[str, Path])`: Context manager to change the current working directory temporarily. + + +### Mock Utilities + +- `does_not_raise`: A context manager for assertions that no exceptions are raised. +- [`reset_environ_after_test`](./src/aibs_informatics_test_resources/utils.py): A decorator to reset environment variables after a test. + +### Example Usage + +Here is an example of how to use the `BaseTest` class in your tests: + +```python +from aibs_informatics_test_resources import BaseTest + +class MyTest(BaseTest): + def test_example(self): + self.assertEqual(1 + 1, 2) + + def test_use_temp_file(self): + with self.tmp_file(content="Hello, World!") as tmp_file: + self.assertTrue(tmp_file.exists()) + self.assertEqual(tmp_file.read_text(), "Hello, World!") + +``` + +## Contributing +Any and all PRs are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information. + +## Licensing +This software is licensed under the Allen Institute Software License, which is the 2-clause BSD license plus a third clause that prohibits redistribution and use for commercial purposes without further permission. For more information, please visit [Allen Institute Terms of Use](https://alleninstitute.org/terms-of-use/). \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index fa0d083..151fd53 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,11 +3,6 @@ # https://setuptools.pypa.io/en/latest/setuptools.html#building-and-distributing-packages-with-setuptools # ----------------------------------------------------------------------------- -# [build-system] -# requires = ["setuptools>=61", "setuptools_scm[toml]>=6.2", "wheel"] -# build-backend = "setuptools.build_meta" -# [tool.setuptools_scm] - [build-system] requires = ["hatchling"] build-backend = "hatchling.build" @@ -15,26 +10,42 @@ build-backend = "hatchling.build" # ----------------------------------------------------------------------------- [project] name = "aibs-informatics-test-resources" -description = "unit test resources for informatics packages" +authors = [{ name = "AIBS Informatics Group"}] +maintainers = [{ name = "AIBS Informatics Group", email = "marmot@alleninstitute.onmicrosoft.com"}] +description = "unit test resources for AIBS informatics packages" +license = { file = "LICENSE" } dynamic = ["version"] requires-python = ">=3.9" dependencies = [ "black==23.11.0", - "coverage[toml]~=7.3.2", + "coverage[toml]~=7.3", "flake8~=6.1.0", "isort~=5.10", - "mypy~=1.6.1", - "pytest~=7.4.3", + "mypy~=1.6", + "pytest~=7.4", "pytest-cov", ] +[project.optional-dependencies] + +release = [ + "build", + "twine", + "wheel", +] + [tool.setuptools.packages.find] where = ["src"] [tool.hatch.version] path = "src/aibs_informatics_test_resources/__version__.py" +[project.urls] +Documentation = "https://.github.io/aibs-informatics-test-resources/" +Homepage = "https://github.com/AllenInstitute/aibs-informatics-test-resources/" +Issues = "https://github.com/AllenInstitute/aibs-informatics-test-resources/issues" +Repository = "https://github.com/AllenInstitute/aibs-informatics-test-resources/" # ----------------------------------------------------------------------------- ## Pyright Configurations