From bc2cc409d9e9d22aa01ec817d4151c8c11b559ca Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 9 Mar 2024 16:13:09 +0100 Subject: [PATCH 01/18] chore(build): improve makefile --- Makefile | 75 +++++++++++++++++++++++++++++--------------------------- 1 file changed, 39 insertions(+), 36 deletions(-) diff --git a/Makefile b/Makefile index 4a0594095..aa9dba9ba 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,9 @@ +.DEFAULT_GOAL := help + + PYTHON_VERSIONS = 3.9 3.10 3.11 PYTHON_VERSION ?= 3.10 IMAGE = testcontainers-python:${PYTHON_VERSION} -RUN = docker run --rm -it # Get all directories that contain a setup.py and get the directory name. PACKAGES = core $(addprefix modules/,$(notdir $(wildcard modules/*))) @@ -15,70 +17,71 @@ DOCTESTS = $(addsuffix /doctests,$(filter-out modules/README.md,${PACKAGES})) # All linting targets. LINT = $(addsuffix /lint,${PACKAGES}) -# Targets to build a distribution for each package. -dist: ${DISTRIBUTIONS} -${DISTRIBUTIONS} : %/dist : %/setup.py - cd $* \ - && python setup.py bdist_wheel \ - && twine check dist/* -# Targets to run the test suite for each package. -tests : ${TESTS} -${TESTS} : %/tests : +install: ## Set up the project for development + poetry install --all-extras + poetry run pre-commit install + +dist: ## Build the python package + poetry build && poerry run twine check dist/* + +tests: ${TESTS} ## Run tests for each package +${TESTS}: %/tests: poetry run pytest -v --cov=testcontainers.$* $*/tests -# Target to combine and report coverage. -coverage: +coverage: ## Target to combine and report coverage. poetry run coverage combine poetry run coverage report poetry run coverage xml poetry run coverage html -# Target to lint the code. -lint: +lint: ## Lint all files in the project, which we also run in pre-commit pre-commit run -a -# Targets to publish packages. -upload : ${UPLOAD} -${UPLOAD} : %/upload : - if [ ${TWINE_REPOSITORY}-$* = testpypi-meta ]; then \ - echo "Cannot upload meta package to testpypi because of missing permissions."; \ - else \ - twine upload --non-interactive --skip-existing $*/dist/*; \ - fi - # Targets to build docker images image: poetry export -f requirements.txt -o build/requirements.txt docker build --build-arg version=${PYTHON_VERSION} -t ${IMAGE} . -# Targets to run tests in docker containers -tests-dind : ${TESTS_DIND} -${TESTS_DIND} : %/tests-dind : image - ${RUN} -v /var/run/docker.sock:/var/run/docker.sock ${IMAGE} \ +DOCKER_RUN = docker run --rm -it + +tests-dind: ${TESTS_DIND} ## Run the tests in docker containers to test `dind` +${TESTS_DIND}: %/tests-dind: image + ${DOCKER_RUN} -v /var/run/docker.sock:/var/run/docker.sock ${IMAGE} \ bash -c "make $*/lint $*/tests" -# Target to build the documentation -docs : +docs: ## Build the docs for the project poetry run sphinx-build -nW . docs/_build # Target to build docs watching for changes as per https://stackoverflow.com/a/21389615 docs-watch : poetry run sphinx-autobuild . docs/_build # requires 'pip install sphinx-autobuild' -doctests : ${DOCTESTS} +doctest: ${DOCTESTS} ## Run doctests found across the documentation. poetry run sphinx-build -b doctest . docs/_build -${DOCTESTS} : %/doctests : +${DOCTESTS}: %/doctest: ## Run doctests found for a module. poetry run sphinx-build -b doctest -c doctests $* docs/_build -# Remove any generated files. -clean : + +clean: ## Remove generated files. rm -rf docs/_build - rm -rf */build - rm -rf */dist + rm -rf build + rm -rf dist rm -rf */*.egg-info +clean-all: clean ## Remove all generated files and reset the local virtual environment + rm -rf .venv + # Targets that do not generate file-level artifacts. -.PHONY : clean dists ${DISTRIBUTIONS} docs doctests image tests ${TESTS} +.PHONY: clean dists ${DISTRIBUTIONS} docs doctests image tests ${TESTS} + + +# Implements this pattern for autodocumenting Makefiles: +# https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html +# +# Picks up all comments that start with a ## and are at the end of a target definition line. +.PHONY: help +help: ## Display command usage + @grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' From 8fdff6c422365f38ef418fd421e16abbb01f7d22 Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 9 Mar 2024 16:30:59 +0100 Subject: [PATCH 02/18] fix: run pre-commit through poetry when calling through make --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index aa9dba9ba..0df0cc709 100644 --- a/Makefile +++ b/Makefile @@ -36,7 +36,7 @@ coverage: ## Target to combine and report coverage. poetry run coverage html lint: ## Lint all files in the project, which we also run in pre-commit - pre-commit run -a + poetry run pre-commit run -a # Targets to build docker images image: From 9ac3b0889be502079e25d38fab448ad73bf51f6a Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 9 Mar 2024 16:31:41 +0100 Subject: [PATCH 03/18] docs(contributing): add CONTRIBUTING.md and draft of new-container.md --- .github/CONTRIBUTING.md | 62 +++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/new-container.md | 22 +++++++++ 2 files changed, 84 insertions(+) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/new-container.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..4c65bfbd8 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing to `testcontainers-python` + +Welcome to the `testcontainers-python` community! +This should give you an idea about how we build, test and release `testcontainers-python`! + +Highly recommended to read this document thoroughly to understand what we're working on right now +and what our priorities are before you are trying to contribute something. + +This will greatly increase your chances of getting prompt replies as the maintainers are volunteers themselves. + +## Before you Begin + +We recommend following these steps: + +1. Finish readng this document. +2. Read the [recently updated issues][1] +3. Look for existing issues on the subject you are interested in - we do our best to label everything correctly + + +## Local Development + +### Pre-Requisites + +You need to have the following tools available to you: +- `make` - You'll need a GNU Make for common developer activities +- `poetry` - This is the primary package manager for the project +- `pyenv` **Recommended**: For installing python versions for your system. + Poetry infers the current latest version from what it can find on the `PATH` so you are still fine if you don't use `pyenv`. + +### Build and test + + +- Run `make install` to get `poetry` to install all dependencies and set up `pre-commit` + - **Recommended**: Run `make` or `make help` to see other commands available to you. +- After this, you should have a working virtual environment and proceed with writing code with your favourite IDE +- **TIP**: You can run `make core/tests` or `make module//tests` to run the tests specifically for that to speed up feedback cycles + + +## Adding new containers + +We have an [issue template](.github/ISSUE_TEMPLATE/new-container.md) for adding new containers, please refer to that for more information. +Once you've talked to the maintainers (we do our best to reply!) then you can proceed with contributing the new container. + +> [!WARNING] +> PLease raise an issue before you try to contribute a new container! It helps maintainers understand your use-case and motivation. +> This way we can keep pull requests foruced on the "how", not the "why"! :pray: +> It also gives maintainers a chance to give you last-minute guidance on caveats or expectations, particularly with +> new extra dependencies and how to manage them. + + +## Raising Issues + +We have [Issue Templates][2] to cover most cases, please try to adhere to them, they will guide you through the process. +Try to look through the existing issues before you raise a new one. + + +# Thank you! + +Thanks for reading, feedback on documentation is always welcome! + +[1]: https://github.com/testcontainers/testcontainers-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc "Recently Updated Issues showing you what we're focusing on" +[2]: https://github.com/testcontainers/testcontainers-python/issues/new/choose "List of current issue templates, please use them" diff --git a/.github/ISSUE_TEMPLATE/new-container.md b/.github/ISSUE_TEMPLATE/new-container.md new file mode 100644 index 000000000..9ad84c5ef --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-container.md @@ -0,0 +1,22 @@ +--- +name: New Container +about: Tell the Testcontainers-Python team about a container you'd like to have support for. +title: 'New Container: ' +labels: '🚀 enhancement' +assignees: '' + +--- + + + +**What is the new container you'd like to have?** + +Please link some docker containers as well as documentation to the bene + +**Why not just use a generic container this?** + +PLease describe why + +**Other references:** + +Include any other relevant reading material about the enhancement. From 57017f9151030e60a50a580693b9403f033c3075 Mon Sep 17 00:00:00 2001 From: Dave Ankin Date: Sat, 9 Mar 2024 17:27:57 -0500 Subject: [PATCH 04/18] nits --- .github/ISSUE_TEMPLATE/new-container.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/new-container.md b/.github/ISSUE_TEMPLATE/new-container.md index 9ad84c5ef..2d91aefe0 100644 --- a/.github/ISSUE_TEMPLATE/new-container.md +++ b/.github/ISSUE_TEMPLATE/new-container.md @@ -13,9 +13,9 @@ assignees: '' Please link some docker containers as well as documentation to the bene -**Why not just use a generic container this?** +**Why not just use a generic container for this?** -PLease describe why +Please describe why **Other references:** From f8605961395a3b0010746752049a965a80317101 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1lint=20Bartha?= <39852431+totallyzen@users.noreply.github.com> Date: Mon, 25 Mar 2024 15:19:06 +0100 Subject: [PATCH 05/18] fix: typo in .github/CONTRIBUTING.md ... based on @jankatins Co-authored-by: Jan Katins --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 4c65bfbd8..87f9adeae 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -12,7 +12,7 @@ This will greatly increase your chances of getting prompt replies as the maintai We recommend following these steps: -1. Finish readng this document. +1. Finish reading this document. 2. Read the [recently updated issues][1] 3. Look for existing issues on the subject you are interested in - we do our best to label everything correctly From 15583e2274be86bc5dc954ed3d0fddad8c0a223a Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 20:48:07 +0100 Subject: [PATCH 06/18] fix: groom question issue template --- .github/ISSUE_TEMPLATE/question.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index 9a7af6ead..b05282d90 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -9,27 +9,33 @@ assignees: '' -**What are you trying to do?** +## What are you trying to do? Ask your question here -**Where are you trying to do it?** +## Where are you trying to do it? Provide a self-contained code snippet that illustrates the bug or unexpected behavior. Ideally, include a link to a public repository with a minimal project where someone from the testcontainers-python can submit a PR with a solution to the problem you are facing with the library. -**Runtime environment** +## Runtime environment -Provide a summary of your runtime environment. Which operating system, python version, and docker version are you using? What is the version of `testcontainers-python` you are using? You can run the following commands to get the relevant information. +Provide a summary of your runtime environment. Which operating system, python version, and docker version are you using? +What is the version of `testcontainers-python` you are using? You can run the following commands to get the relevant information. + +Paste the results of the bash below + +```bash +uname -a +echo "------" +docker info +echo "------" +poetry run python --version +echo "------" +poetry show --tree +``` ```bash -# Get the operating system information (on a unix os). -$ uname -a -# Get the python version. -$ python --version -# Get the docker version and other docker information. -$ docker info -# Get all python packages. -$ pip freeze +paste-me-here ``` From f5e8e512edb3bca666a83ffd1b62b84eb0c7620b Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 21:13:50 +0100 Subject: [PATCH 07/18] docs: add stuff on adding new containers --- .github/ISSUE_TEMPLATE/new-container.md | 8 +++- .../PULL_REQUEST_TEMPLATE/new_container.md | 46 +++++++++++++++---- 2 files changed, 44 insertions(+), 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/new-container.md b/.github/ISSUE_TEMPLATE/new-container.md index 2d91aefe0..5da4f509e 100644 --- a/.github/ISSUE_TEMPLATE/new-container.md +++ b/.github/ISSUE_TEMPLATE/new-container.md @@ -11,11 +11,15 @@ assignees: '' **What is the new container you'd like to have?** -Please link some docker containers as well as documentation to the bene +Please link some docker containers as well as documentation to the benefits of having this container. **Why not just use a generic container for this?** -Please describe why +Please describe why the `DockerContainer("my-image:latest")` approach is not useful enough. + +Having a dedicated `TestContainer` usually means the need for some or all of these: +- complicated setup/configuration +- the wait strategy is complex for the container, usually more than just an http wait **Other references:** diff --git a/.github/PULL_REQUEST_TEMPLATE/new_container.md b/.github/PULL_REQUEST_TEMPLATE/new_container.md index 29b8190d4..d08d3e581 100644 --- a/.github/PULL_REQUEST_TEMPLATE/new_container.md +++ b/.github/PULL_REQUEST_TEMPLATE/new_container.md @@ -1,8 +1,38 @@ -You have implemented a new container and would like to contribute it? Great! Here are the necessary steps. - -- [ ] Create a new feature directory and populate it with the package structure [described in the documentation](https://testcontainers-python.readthedocs.io/en/latest/#package-structure). Copying one of the existing features is likely the best way to get started. -- [ ] Implement the new feature (typically in `__init__.py`) and corresponding tests. -- [ ] Update the feature `README.rst` and add it to the table of contents (`toctree` directive) in the top-level `README.rst`. -- [ ] Add a line `[feature name]` to the list of components in the GitHub Action workflow in `.github/workflows/main.yml` to run tests, build, and publish your package when pushed to the `main` branch. -- [ ] Rebase your development branch on `main` (or merge `main` into your development branch). -- [ ] Add a line `-e file:[feature name]` to `requirements.in` and open a pull request. Opening a pull request will automatically generate lock files to ensure reproducible builds (see the [pip-tools documentation](https://pip-tools.readthedocs.io/en/latest/) for details). Finally, run `python get_requirements.py --pr=[your PR number]` to fetch the updated requirement files (the build needs to have succeeded). +# New Container + + + +Fixes ... + + + + +# PR Checklist + +- [ ] Your PR allows maintainers to edit your branch, this will speed up resolving minor issues! +- [ ] The new container is implemented under `modules/*` + - Your module follows [PEP 420](https://peps.python.org/pep-0420/) with implicit namespace packages + (if unsure, look at other existing community modules) + - Your package namespacing follows `testcontainers..*` + and you DO NOT have an `__init__.py` above your module's level. + - Your module has it's own tests under `modules/*/tests` + - Your module has a `README.rst` and hooks in the `.. auto-class` and `.. title` of your container + - Implement the new feature (typically in `__init__.py`) and corresponding tests. +- [ ] Your module is added in `pyproject.toml` + - it is declared under `tool.poetry.packages` - see other community modules + - it is declared under `tool.poetry.extras` with the same name as your module name, + we still prefer adding _NO EXTRA DEPENDENCIES_, meaning `mymodule = []` is the preferred addition + (see the notes at the bottom) +- [ ] The `INDEX.rst` at the project root includes your module under the `.. toctree` directive +- [ ] Your branch is up to date (or we'll use GH's "update branch" function through the UI) + +# Preferred implementation + +- The current consensus among maintainers is to try to avoid enforcing the client library + for the given tools you are triyng to implement. +- This means we want you to avoid adding specific libraries as dependencies to `testcontainers`. +- Therefore, you should implement the configuration and the waiting with as little extra as possible +- You may still find it useful to add your preferred client library as a dev dependency From ef904505771296f7441ef66253af3f270de55e02 Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:06:58 +0100 Subject: [PATCH 08/18] fix: clean up Makefile, make it more coherent, even if dind is still defunct --- Dockerfile | 9 ++++++--- Makefile | 26 +++++++++----------------- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/Dockerfile b/Dockerfile index 4172f86fe..c86c9e2df 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ -ARG version=3.8 -FROM python:${version} +ARG PYTHON_VERSION +FROM python:${version}-slim-bookworm WORKDIR /workspace RUN pip install --upgrade pip \ @@ -7,7 +7,10 @@ RUN pip install --upgrade pip \ && apt-get install -y \ freetds-dev \ && rm -rf /var/lib/apt/lists/* + +# install requirements we exported from poetry COPY build/requirements.txt requirements.txt -COPY setup.py README.rst ./ RUN pip install -r requirements.txt + +# copy project source COPY . . diff --git a/Makefile b/Makefile index 0df0cc709..cad38f2d0 100644 --- a/Makefile +++ b/Makefile @@ -1,29 +1,23 @@ .DEFAULT_GOAL := help -PYTHON_VERSIONS = 3.9 3.10 3.11 PYTHON_VERSION ?= 3.10 IMAGE = testcontainers-python:${PYTHON_VERSION} # Get all directories that contain a setup.py and get the directory name. PACKAGES = core $(addprefix modules/,$(notdir $(wildcard modules/*))) -# All */dist folders for each of the packages. -DISTRIBUTIONS = $(addsuffix /dist,${PACKAGES}) UPLOAD = $(addsuffix /upload,${PACKAGES}) -# All */tests folders for each of the test suites. TESTS = $(addsuffix /tests,$(filter-out meta,${PACKAGES})) TESTS_DIND = $(addsuffix -dind,${TESTS}) -DOCTESTS = $(addsuffix /doctests,$(filter-out modules/README.md,${PACKAGES})) -# All linting targets. -LINT = $(addsuffix /lint,${PACKAGES}) +DOCTESTS = $(addsuffix /doctest,$(filter-out meta,${PACKAGES})) install: ## Set up the project for development poetry install --all-extras poetry run pre-commit install -dist: ## Build the python package - poetry build && poerry run twine check dist/* +build: ## Build the python package + poetry build && poetry run twine check dist/* tests: ${TESTS} ## Run tests for each package ${TESTS}: %/tests: @@ -38,18 +32,16 @@ coverage: ## Target to combine and report coverage. lint: ## Lint all files in the project, which we also run in pre-commit poetry run pre-commit run -a -# Targets to build docker images -image: +image: ## Make the docker image for dind tests poetry export -f requirements.txt -o build/requirements.txt - docker build --build-arg version=${PYTHON_VERSION} -t ${IMAGE} . + docker build --build-arg PYTHON_VERSION=${PYTHON_VERSION} -t ${IMAGE} . - -DOCKER_RUN = docker run --rm -it +DOCKER_RUN = docker run --rm -v /var/run/docker.sock:/var/run/docker.sock tests-dind: ${TESTS_DIND} ## Run the tests in docker containers to test `dind` ${TESTS_DIND}: %/tests-dind: image - ${DOCKER_RUN} -v /var/run/docker.sock:/var/run/docker.sock ${IMAGE} \ - bash -c "make $*/lint $*/tests" + ${DOCKER_RUN} ${IMAGE} \ + bash -c "make $*/tests" docs: ## Build the docs for the project poetry run sphinx-build -nW . docs/_build @@ -75,7 +67,7 @@ clean-all: clean ## Remove all generated files and reset the local virtual envir rm -rf .venv # Targets that do not generate file-level artifacts. -.PHONY: clean dists ${DISTRIBUTIONS} docs doctests image tests ${TESTS} +.PHONY: clean docs doctests image tests ${TESTS} # Implements this pattern for autodocumenting Makefiles: From cb77560057a8aa996c68b8ebbf8d19b71cca6904 Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:08:30 +0100 Subject: [PATCH 09/18] fix: nit wording --- .github/ISSUE_TEMPLATE/new-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/new-container.md b/.github/ISSUE_TEMPLATE/new-container.md index 5da4f509e..b089c2e18 100644 --- a/.github/ISSUE_TEMPLATE/new-container.md +++ b/.github/ISSUE_TEMPLATE/new-container.md @@ -11,7 +11,7 @@ assignees: '' **What is the new container you'd like to have?** -Please link some docker containers as well as documentation to the benefits of having this container. +Please link some docker containers as well as documentation/arguments to the benefits of having this container. **Why not just use a generic container for this?** From 2b6fefebe58bb6f7baec3e8b138c109226376394 Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:13:05 +0100 Subject: [PATCH 10/18] fix: refer to make lint in contributing.md --- .github/CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 87f9adeae..33d3c8ae2 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -34,6 +34,7 @@ You need to have the following tools available to you: - **Recommended**: Run `make` or `make help` to see other commands available to you. - After this, you should have a working virtual environment and proceed with writing code with your favourite IDE - **TIP**: You can run `make core/tests` or `make module//tests` to run the tests specifically for that to speed up feedback cycles +- You can also run `make lint` to run the `pre-commit` for the entire codebase. ## Adding new containers From 8acd06097fef1f52e6a80e4a8bd30bd28b3dcd72 Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:21:57 +0100 Subject: [PATCH 11/18] fix: small typo --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index cad38f2d0..152190e53 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ PACKAGES = core $(addprefix modules/,$(notdir $(wildcard modules/*))) UPLOAD = $(addsuffix /upload,${PACKAGES}) TESTS = $(addsuffix /tests,$(filter-out meta,${PACKAGES})) TESTS_DIND = $(addsuffix -dind,${TESTS}) -DOCTESTS = $(addsuffix /doctest,$(filter-out meta,${PACKAGES})) +DOCTESTS = $(addsuffix /doctest,$(filter-out modules/README.md,${PACKAGES})) install: ## Set up the project for development From f7866a4634b1b90cfc25e5bb7759b56de54d47da Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:25:17 +0100 Subject: [PATCH 12/18] fix: go back to /doctests (in plural form) --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 152190e53..43ed82813 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ PACKAGES = core $(addprefix modules/,$(notdir $(wildcard modules/*))) UPLOAD = $(addsuffix /upload,${PACKAGES}) TESTS = $(addsuffix /tests,$(filter-out meta,${PACKAGES})) TESTS_DIND = $(addsuffix -dind,${TESTS}) -DOCTESTS = $(addsuffix /doctest,$(filter-out modules/README.md,${PACKAGES})) +DOCTESTS = $(addsuffix /doctests,$(filter-out modules/README.md,${PACKAGES})) install: ## Set up the project for development @@ -50,10 +50,10 @@ docs: ## Build the docs for the project docs-watch : poetry run sphinx-autobuild . docs/_build # requires 'pip install sphinx-autobuild' -doctest: ${DOCTESTS} ## Run doctests found across the documentation. +doctests: ${DOCTESTS} ## Run doctests found across the documentation. poetry run sphinx-build -b doctest . docs/_build -${DOCTESTS}: %/doctest: ## Run doctests found for a module. +${DOCTESTS}: %/doctests: ## Run doctests found for a module. poetry run sphinx-build -b doctest -c doctests $* docs/_build From c823a3570948d16d57da64283c0e254dd972168e Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:40:16 +0100 Subject: [PATCH 13/18] fix: reference conventional commits as it's important to development --- .github/PULL_REQUEST_TEMPLATE/new_container.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE/new_container.md b/.github/PULL_REQUEST_TEMPLATE/new_container.md index d08d3e581..27057310d 100644 --- a/.github/PULL_REQUEST_TEMPLATE/new_container.md +++ b/.github/PULL_REQUEST_TEMPLATE/new_container.md @@ -12,6 +12,8 @@ It helps reduce unnecessary work for you and the maintainers! # PR Checklist +- [ ] Your PR title follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) syntax + as we make use of this for detecting Semantic Versioning changes. - [ ] Your PR allows maintainers to edit your branch, this will speed up resolving minor issues! - [ ] The new container is implemented under `modules/*` - Your module follows [PEP 420](https://peps.python.org/pep-0420/) with implicit namespace packages From 6466528babd8a09bb8dd7578dcf5c09c680d70fb Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:40:44 +0100 Subject: [PATCH 14/18] fix: remove setup.py references and refer to poetry --- Makefile | 1 - index.rst | 27 +++++++++++++++------------ 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/Makefile b/Makefile index 43ed82813..9a4fd6f94 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,6 @@ PYTHON_VERSION ?= 3.10 IMAGE = testcontainers-python:${PYTHON_VERSION} -# Get all directories that contain a setup.py and get the directory name. PACKAGES = core $(addprefix modules/,$(notdir $(wildcard modules/*))) UPLOAD = $(addsuffix /upload,${PACKAGES}) diff --git a/index.rst b/index.rst index 6e7ed596c..e20ff62db 100644 --- a/index.rst +++ b/index.rst @@ -60,9 +60,9 @@ Installation ------------ The suite of testcontainers packages is available on `PyPI `_, -and individual packages can be installed using :code:`pip`. +and the package can be installed using :code:`pip`. -Version `4.0.0` onwards we do not support the `testcontainers-*` packages as it is unsutainable to maintain ownership. +Version `4.0.0` onwards we do not support the `testcontainers-*` packages as it is unsustainable to maintain ownership. Instead packages can be installed by specifying `extras `__, e.g., :code:`pip install testcontainers[postgres]`. @@ -70,7 +70,7 @@ Instead packages can be installed by specifying `extras `_) or install the client from within the `Dockerfile` specification. 2. The container has to have access to the docker daemon which can be achieved by mounting `/var/run/docker.sock` or setting the `DOCKER_HOST` environment variable as part of your `docker run` command. @@ -124,17 +124,21 @@ Configuration Development and Contributing ---------------------------- -We recommend you use a `virtual environment `_ for development (:code:`python>=3.7` is required). After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet. +We recommend you use a `Poetry `_ for development. +After having installed `poetry`, you can run the following snippet to set up your local dev environment. .. code-block:: bash - poetry install --all-extras - make /tests + make install Package Structure ^^^^^^^^^^^^^^^^^ -Testcontainers is a collection of `implicit namespace packages `__ to decouple the development of different extensions, e.g., :code:`testcontainers-mysql` and :code:`testcontainers-postgres` for MySQL and PostgreSQL database containers, respectively. The folder structure is as follows. +Testcontainers is a collection of `implicit namespace packages `__ +to decouple the development of different extensions, +e.g., :code:`testcontainers-mysql` and :code:`testcontainers-postgres` for MySQL and PostgreSQL database containers, respectively. + +The folder structure is as follows: .. code-block:: bash @@ -154,12 +158,11 @@ Testcontainers is a collection of `implicit namespace packages `_. +You want to contribute a new feature or container? Great! +- We recommend you first `open an issue `_ +- Then follow the suggestions from the team +- We also have a Pull Request `template `_ for new containers! From 277854844dde6e1c0d4feb07be710a692fcea22e Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 23:13:45 +0100 Subject: [PATCH 15/18] docs: document community module support facts --- .github/CONTRIBUTING.md | 11 +++++++++++ index.rst | 3 +++ 2 files changed, 14 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 33d3c8ae2..f9953c5fa 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -55,6 +55,17 @@ We have [Issue Templates][2] to cover most cases, please try to adhere to them, Try to look through the existing issues before you raise a new one. +## Releasing Versions + +We have automated Semantic Versioning and release via [release-please](workflows/release-please.yml). +This takes care of: +- Detecting the next version, based on the commits that landed on `main` +- When a Release PR has been merged + - Create a GitHub Release with the CHANGELOG included + - Update the [CHANGELOG](../CHANGELOG.md), similar to the GitHub Release + - Release to PyPI via a [trusted publisher](https://docs.pypi.org/trusted-publishers/using-a-publisher/) + - Automatically script updates in files where it's needed instead of hand-crafting it (i.e. in `pyproject.toml`) + # Thank you! Thanks for reading, feedback on documentation is always welcome! diff --git a/index.rst b/index.rst index e20ff62db..21c009fa2 100644 --- a/index.rst +++ b/index.rst @@ -66,6 +66,9 @@ Version `4.0.0` onwards we do not support the `testcontainers-*` packages as it Instead packages can be installed by specifying `extras `__, e.g., :code:`pip install testcontainers[postgres]`. +Please note, that community modules are supported on a best-effort basis and breaking changes DO NOT create major versions in the package. +Therefore, only the package core is strictly following SemVer. If your workflow is broken by a minor update, please look at the changelogs for guidance. + Docker in Docker (DinD) ----------------------- From 874f063a81b27c386cf7308e6be293b6c0a57657 Mon Sep 17 00:00:00 2001 From: Balint Bartha <39852431+totallyzen@users.noreply.github.com> Date: Sat, 30 Mar 2024 23:22:04 +0100 Subject: [PATCH 16/18] fix: add more warnings and explanation --- .github/CONTRIBUTING.md | 8 ++++++++ README.md | 4 ++++ 2 files changed, 12 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f9953c5fa..12c8d19fa 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -66,6 +66,14 @@ This takes care of: - Release to PyPI via a [trusted publisher](https://docs.pypi.org/trusted-publishers/using-a-publisher/) - Automatically script updates in files where it's needed instead of hand-crafting it (i.e. in `pyproject.toml`) +> [!CRITICAL] +> Community modules are supported on a best-effort basis and for maintenance reasons, any change to them +> is only covered under minor and patch changes. +> +> Community modules changes DO NOT contribute to major version changes! +> +> If your community module container was broken by a minor or patch version change, check out the change logs! + # Thank you! Thanks for reading, feedback on documentation is always welcome! diff --git a/README.md b/README.md index 434d0698a..114426f52 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,10 @@ For more information, see [the docs][readthedocs]. The snippet above will spin up a postgres database in a container. The `get_connection_url()` convenience method returns a `sqlalchemy` compatible url we use to connect to the database and retrieve the database version. +## Contributing / Development / Release + +See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more details. + ## Configuration | Env Variable | Example | Description | From d55b6ec6acc37893eb3af16ef797ffd8fbc31505 Mon Sep 17 00:00:00 2001 From: Max Pfeiffer Date: Fri, 5 Apr 2024 16:56:52 +0200 Subject: [PATCH 17/18] docs: Added badges to README.md (#528) I added the following badges: - Poetry - Ruff - Supported Python versions - Workflow runs --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 114426f52..cec096a47 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,14 @@ +[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/) [![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) -[![image](https://img.shields.io/pypi/v/testcontainers.svg)](https://pypi.python.org/pypi/testcontainers) -[![image](https://img.shields.io/pypi/l/testcontainers.svg)](https://github.com/testcontainers/testcontainers-python/blob/main/LICENSE) -[![image](https://img.shields.io/pypi/pyversions/testcontainers.svg)](https://pypi.python.org/pypi/testcontainers) +![PyPI - Version](https://img.shields.io/pypi/v/testcontainers) +[![PyPI - License](https://img.shields.io/pypi/l/testcontainers.svg)](https://github.com/testcontainers/testcontainers-python/blob/main/LICENSE) +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/testcontainers.svg)](https://pypi.python.org/pypi/testcontainers) [![codecov](https://codecov.io/gh/testcontainers/testcontainers-python/branch/master/graph/badge.svg)](https://codecov.io/gh/testcontainers/testcontainers-python) +![Core Tests](https://github.com/testcontainers/testcontainers-python/actions/workflows/ci-core.yml/badge.svg) +![Community Tests](https://github.com/testcontainers/testcontainers-python/actions/workflows/ci-community.yml/badge.svg) +[![Docs](https://readthedocs.org/projects/testcontainers-python/badge/?version=latest)](http://testcontainers-python.readthedocs.io/en/latest/?badge=latest) +[![Codespace](https://github.com/codespaces/badge.svg)](https://codespaces.new/testcontainers/testcontainers-python) # Testcontainers Python From 1276acbf613d2518c5d04dbaf041013db92c99af Mon Sep 17 00:00:00 2001 From: David Ankin Date: Wed, 17 Apr 2024 06:51:16 -0400 Subject: [PATCH 18/18] replace child packages with extras notation for package structure section --- index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.rst b/index.rst index 21c009fa2..af3142831 100644 --- a/index.rst +++ b/index.rst @@ -139,7 +139,7 @@ Package Structure Testcontainers is a collection of `implicit namespace packages `__ to decouple the development of different extensions, -e.g., :code:`testcontainers-mysql` and :code:`testcontainers-postgres` for MySQL and PostgreSQL database containers, respectively. +e.g., :code:`testcontainers[mysql]` and :code:`testcontainers[postgres]` for MySQL and PostgreSQL database containers, respectively. The folder structure is as follows: