Skip to content

Commit e04582f

Browse files
tillahoffmanntillahoffmann
committed
Update instructions for contributing new features.
1 parent 2bfbdb9 commit e04582f

File tree

2 files changed

+57
-34
lines changed

2 files changed

+57
-34
lines changed

‎.github/PULL_REQUEST_TEMPLATE/new_container.md

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
You have implemented a new container and would like to contribute it? Great! Here are the necessary steps:
1+
You have implemented a new container and would like to contribute it? Great! Here are the necessary steps.
22

3-
- [ ] You have added the new container as a module in the `testcontainers` directory (such as `testcontainers/my_fancy_container.py`).
4-
- [ ] You have added any new python dependencies in the `extras_require` section of `setup.py`.
5-
- [ ] You have added the `extra_requires` key to `requirements.in`.
6-
- [ ] You have updated all python requirements by running `make requirements` from the root directory.
7-
- [ ] You have added tests for the new container in the `tests` directory, e.g. `tests/test_my_fancy_container.py`.
8-
- [ ] You have added the name of the container (such as `my_fancy_container`) to the `test-components` matrix in `.github/workflows/main.yml` to ensure the tests are run.
9-
- [ ] You have rebased your development branch on `master` (or merged `master` into your development branch).
3+
- [ ] 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.
4+
- [ ] Implement the new feature (typically in `__init__.py`) and corresponding tests.
5+
- [ ] Add a line `-e file:[feature name]` to `requirements.in` and run `make requirements`. This command will find any new requirements and generate lock files to ensure reproducible builds (see the [pip-tools documentation](https://pip-tools.readthedocs.io/en/latest/) for details). Then run `pip install -r requirements/[your python version].txt` to install the new requirements.
6+
- [ ] Update the feature `README.rst` and add it to the table of contents (`toctree` directive) in the top-level `README.rst`.
7+
- [ ] 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 `master` branch.
8+
- [ ] Rebase your development branch on `master` (or merge `master` into your development branch).

‎README.rst

Lines changed: 50 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ testcontainers-python
33

44
.. image:: https://github.com/testcontainers/testcontainers-python/workflows/testcontainers-python/badge.svg
55
:target: https://github.com/testcontainers/testcontainers-python/actions/workflows/main.yml
6-
.. image:: https://img.shields.io/pypi/v/testcontainers.svg?style=flat-square
6+
.. image:: https://img.shields.io/pypi/v/testcontainers.svg
77
:target: https://pypi.python.org/pypi/testcontainers
88
.. image:: https://readthedocs.org/projects/testcontainers-python/badge/?version=latest
99
:target: http://testcontainers-python.readthedocs.io/en/latest/?badge=latest
@@ -35,18 +35,17 @@ testcontainers-python facilitates the use of Docker containers for functional an
3535
redis/README
3636
selenium/README
3737

38-
Basic usage
39-
-----------
38+
Getting Started
39+
---------------
4040

4141
.. doctest::
4242

4343
>>> from testcontainers.postgres import PostgresContainer
4444
>>> import sqlalchemy
4545

46-
>>> postgres_container = PostgresContainer("postgres:9.5")
47-
>>> with postgres_container as postgres:
48-
... e = sqlalchemy.create_engine(postgres.get_connection_url())
49-
... result = e.execute("select version()")
46+
>>> with PostgresContainer("postgres:9.5") as postgres:
47+
... engine = sqlalchemy.create_engine(postgres.get_connection_url())
48+
... result = engine.execute("select version()")
5049
... version, = result.fetchone()
5150
>>> version
5251
'PostgreSQL 9.5...'
@@ -56,39 +55,64 @@ The snippet above will spin up a postgres database in a container. The :code:`ge
5655
Installation
5756
------------
5857

59-
The suite of testcontainers packages is available on `PyPI <https://pypi.org/project/testcontainers/>`_, and individual packages can be installed using :code:`pip`. We recommend installing the package you need by running :code:`pip install testcontainers-<feature>`, e.g., :code:`pip install testcontainers-mysql`.
58+
The suite of testcontainers packages is available on `PyPI <https://pypi.org/project/testcontainers/>`_, and individual packages can be installed using :code:`pip`. We recommend installing the package you need by running :code:`pip install testcontainers-<feature>`, e.g., :code:`pip install testcontainers-postgres`.
6059

61-
For backwards compatibility, packages can also be installed by specifying `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`__, e.g., :code:`pip install testcontainers[mysql]`.
60+
.. note::
6261

62+
For backwards compatibility, packages can also be installed by specifying `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`__, e.g., :code:`pip install testcontainers[postgres]`.
6363

64-
Usage within Docker (e.g., in a CI)
65-
-----------------------------------
6664

67-
When trying to launch a testcontainer from within a Docker container two things have to be provided:
65+
Docker in Docker (DinD)
66+
-----------------------
67+
68+
When trying to launch a testcontainer from within a Docker container, e.g., in continuous integration testing, two things have to be provided:
6869

6970
1. The container has to provide a docker client installation. Either use an image that has docker pre-installed (e.g. the `official docker images <https://hub.docker.com/_/docker>`_) or install the client from within the `Dockerfile` specification.
7071
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.
7172

72-
Setting up a development environment
73-
------------------------------------
73+
Development and Contributing
74+
----------------------------
7475

75-
We recommend you use a `virtual environment <https://virtualenv.pypa.io/en/stable/>`_ for development. Note that a python version :code:`>=3.7` is required. After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet.
76+
We recommend you use a `virtual environment <https://virtualenv.pypa.io/en/stable/>`_ 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.
7677

7778
.. code-block:: bash
7879
79-
pip install -r requirements/$(python -c 'import sys; print("%d.%d" % sys.version_info[:2])').txt
80+
pip install -r requirements/[your python version].txt
8081
pytest -s
8182
82-
Adding requirements
83-
^^^^^^^^^^^^^^^^^^^
84-
85-
We use :code:`pip-tools` to resolve and manage dependencies. If you need to add a dependency to testcontainers or one of the extras, modify the :code:`setup.py` as well as the :code:`requirements.in` accordingly and then run :code:`pip install pip-tools` followed by :code:`make requirements` to update the requirements files.
83+
Package Structure
84+
^^^^^^^^^^^^^^^^^
8685

87-
Contributing a new container
88-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
86+
Testcontainers is a collection of `implicit namespace packages <https://peps.python.org/pep-0420/>`__ 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.
8987

90-
You can contribute a new container in three steps:
88+
.. code-block:: bash
9189
92-
1. Create a new module at :code:`testcontainers/[my fancy container].py` that implements the new functionality.
93-
2. Create a new test module at :code:`tests/test_[my fancy container].py` that tests the new functionality.
94-
3. Add :code:`[my fancy container]` to the list of test components in the GitHub Action configuration at :code:`.github/workflows/main.yml`.
90+
# One folder per feature.
91+
[feature name]
92+
# Folder without __init__.py for implicit namespace packages.
93+
testcontainers
94+
# Implementation as namespace package with __init__.py.
95+
[feature name]
96+
__init__.py
97+
# Other files for this
98+
...
99+
# Tests for the feature.
100+
tests
101+
test_[feature_name].py
102+
...
103+
# README for this feature.
104+
README.rst
105+
# Setup script for this feature.
106+
setup.py
107+
108+
Contributing a New Feature
109+
^^^^^^^^^^^^^^^^^^^^^^^^^^
110+
111+
You want to contribute a new feature or container? Great! You can do that in six steps.
112+
113+
1. Create a new feature directory and populate it with the [package structure]_ as described above. Copying one of the existing features is likely the best way to get started.
114+
2. Implement the new feature (typically in :code:`__init__.py`) and corresponding tests.
115+
3. Add a line :code:`-e file:[feature name]` to :code:`requirements.in` and run :code:`make requirements`. This command will find any new requirements and generate lock files to ensure reproducible builds (see the `pip-tools <https://pip-tools.readthedocs.io/en/latest/>`__ documentation for details). Then run :code:`pip install -r requirements/[your python version].txt` to install the new requirements.
116+
4. Update the feature :code:`README.rst` and add it to the table of contents (:code:`toctree` directive) in the top-level :code:`README.rst`.
117+
5. Add a line :code:`[feature name]` to the list of components in the GitHub Action workflow in :code:`.github/workflows/main.yml` to run tests, build, and publish your package when pushed to the :code:`master` branch.
118+
6. Rebase your development branch on :code:`master` (or merge :code:`master` into your development branch).

0 commit comments

Comments
 (0)