Skip to content

Commit 56e6b88

Browse files
tillahoffmanntillahoffmann
authored
Update documentation (#88)
* Add information regarding dev environment (fixes #77). * Update requirements and README. * Remove unused quick-start file. * Move docs closer to code. * Add documentation build to CI. * Fix linting errors.
1 parent da4dcc4 commit 56e6b88

28 files changed

+388
-396
lines changed

‎.travis.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ before_script: # add the mssql driver for xenial
2929

3030
script:
3131
- flake8
32+
- sphinx-build -nW docs docs/_build/html
3233
- py.test -sv --cov-config .coveragerc --cov-report html:skip-covered --cov-report term:skip-covered --cov=testcontainers --tb=short tests/
3334
- codecov
3435

‎README.md

Lines changed: 0 additions & 56 deletions
This file was deleted.

‎README.rst

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
testcontainers-python
2+
=====================
3+
4+
.. image:: https://travis-ci.org/testcontainers/testcontainers-python.svg?branch=master
5+
:target: https://travis-ci.org/testcontainers/testcontainers-python
6+
.. image:: https://img.shields.io/pypi/v/testcontainers.svg?style=flat-square
7+
:target: https://pypi.python.org/pypi/testcontainers
8+
.. image:: https://readthedocs.org/projects/testcontainers-python/badge/?version=latest
9+
:target: http://testcontainers-python.readthedocs.io/en/latest/?badge=latest
10+
11+
Python port for testcontainers-java that allows using docker containers for functional and integration testing. Testcontainers-python provides capabilities to spin up docker containers (such as a database, Selenium web browser, or any other container) for testing.
12+
13+
Currently available features:
14+
15+
* Selenium Grid containers
16+
* Selenium Standalone containers
17+
* MySql Db container
18+
* MariaDb container
19+
* OracleDb container
20+
* PostgreSQL Db container
21+
* Microsoft SQL Server container
22+
* Generic docker containers
23+
24+
Installation
25+
------------
26+
27+
The testcontainers package is available from `PyPI <https://pypi.org/project/testcontainers/>`_, and it can be installed using :code:`pip`. Depending on which containers are needed, you can specify additional dependencies as `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_:
28+
29+
.. code-block:: bash
30+
31+
# Install without extras
32+
pip install testcontainers
33+
# Install with one or more extras
34+
pip install testcontainers[mysql]
35+
pip install testcontainers[mysql,oracle]
36+
37+
Basic usage
38+
-----------
39+
40+
.. code-block:: python
41+
42+
import sqlalchemy
43+
from testcontainers.mysql import MySqlContainer
44+
45+
with MySqlContainer('mysql:5.7.17') as mysql:
46+
engine = sqlalchemy.create_engine(mysql.get_connection_url())
47+
version, = engine.execute("select version()").fetchone()
48+
print(version) # 5.7.17
49+
50+
The snippet above will spin up a MySql database in a container. The :code:`get_connection_url()` convenience method returns a :code:`sqlalchemy` compatible url we use to connect to the database and retrieve the database version.
51+
52+
More extensive documentation can be found at `Read The Docs <http://testcontainers-python.readthedocs.io/>`_.
53+
54+
Setting up a development environment
55+
------------------------------------
56+
57+
We recommend you use a `virtual environment <https://virtualenv.pypa.io/en/stable/>`_ for development. Note that a python version :code:`>=3.5` is required. After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet.
58+
59+
.. code-block:: bash
60+
61+
pip install -r requirements/$(python -c 'import sys; print("%d.%d" % sys.version_info[:2])').txt
62+
pytest -s
63+
64+
Adding requirements
65+
^^^^^^^^^^^^^^^^^^^
66+
67+
We use :code:`pip-tools` to resolve and manage dependencies. If you need to add a dependency to testcontainers or one of the extras, run :code:`pip install pip-tools` followed by :code:`make requirements` to update the requirements files.

‎docs/compose.rst

Lines changed: 2 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,2 @@
1-
Docker compose support
2-
======================
3-
4-
Allows to spin up services configured via docker-compose.yml
5-
6-
Example docker-compose.yml for grid
7-
-----------------------------------
8-
9-
::
10-
11-
hub:
12-
image: selenium/hub
13-
ports:
14-
- "4444:4444"
15-
firefox:
16-
image: selenium/node-firefox
17-
links:
18-
- hub
19-
expose:
20-
- "5555"
21-
chrome:
22-
image: selenium/node-chrome
23-
links:
24-
- hub
25-
expose:
26-
- "5555"
27-
28-
Code
29-
----
30-
31-
::
32-
33-
compose = DockerCompose("/home/project", pull=True)
34-
with compose:
35-
host = compose.get_service_host("hub", 4444)
36-
port = compose.get_service_port("hub", 4444)
37-
driver = webdriver.Remote(
38-
command_executor=("http://{}:{}/wd/hub".format(host,port)),
39-
desired_capabilities=CHROME)
40-
driver.get("http://automation-remarks.com")
41-
1+
.. automodule:: testcontainers.compose
2+
:members: DockerCompose

‎docs/conf.py

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,10 @@
3030
# Add any Sphinx extension module names here, as strings. They can be
3131
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3232
# ones.
33-
extensions = []
33+
extensions = [
34+
'sphinx.ext.autodoc',
35+
'sphinx.ext.napoleon',
36+
]
3437

3538
# Add any paths that contain templates here, relative to this directory.
3639
templates_path = ['_templates']
@@ -93,7 +96,7 @@
9396
# Add any paths that contain custom static files (such as style sheets) here,
9497
# relative to this directory. They are copied after the builtin static files,
9598
# so a file named "default.css" will overwrite the builtin "default.css".
96-
html_static_path = ['_static']
99+
# html_static_path = ['_static']
97100

98101

99102
# -- Options for HTMLHelp output ------------------------------------------

‎docs/database.rst

Lines changed: 9 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,129 +1,12 @@
11
Database containers
22
===================
33

4-
Allows to spin up docker database images such as MySQL, PostgreSQL, MariaDB, Oracle XE and MongoDb.
5-
6-
MySQL example
7-
-------------
8-
9-
::
10-
11-
def test_docker_run_mysql():
12-
config = MySqlContainer('mysql:5.7.17')
13-
with config as mysql:
14-
e = sqlalchemy.create_engine(mysql.get_connection_url())
15-
result = e.execute("select version()")
16-
17-
It will spin up MySQL version 5.7. Then you can connect to database with credentials passed in constructor or just
18-
19-
call ``get_connection_url()`` method which returns sqlalchemy compatible url in format ``dialect+driver://username:password@host:port/database``.
20-
21-
PostgresSQL
22-
-----------
23-
24-
Example of PostgresSQL database usage:
25-
26-
::
27-
28-
def test_docker_run_postgress():
29-
postgres_container = PostgresContainer("postgres:9.5")
30-
with postgres_container as postgres:
31-
e = sqlalchemy.create_engine(postgres.get_connection_url())
32-
result = e.execute("select version()")
33-
34-
Connection set by using raw python ``psycopg2`` driver for Postgres.
35-
36-
MariaDB
37-
-------
38-
39-
Maria DB is a fork of MySQL database, so the only difference with MySQL is the name of Docker container.
40-
41-
::
42-
43-
def test_docker_run_mariadb():
44-
mariadb_container = MariaDbContainer("mariadb:latest")
45-
with mariadb_container as mariadb:
46-
e = sqlalchemy.create_engine(mariadb.get_connection_url())
47-
result = e.execute("select version()")
48-
49-
Oracle XE
50-
---------
51-
52-
::
53-
54-
oracle = OracleDbContainer()
55-
56-
with oracle:
57-
e = sqlalchemy.create_engine(oracle.get_connection_url())
58-
result = e.execute("select 1 from dual")
59-
60-
It uses **https://hub.docker.com/r/wnameless/oracle-xe-11g-r2/** docker image.
61-
62-
Necessary to use it:
63-
64-
- ``cx_Oracle``
65-
- `Oracle client libraries <https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html>`_
66-
67-
::
68-
69-
hostname: localhost
70-
port: 49161
71-
sid: xe
72-
username: system
73-
password: oracle
74-
75-
Elasticsearch
76-
-------------
77-
78-
::
79-
80-
es = ElasticSearchContainer()
81-
with es:
82-
es.get_url() # gives you the http URL to connect to Elasticsearch
83-
84-
MongoDb
85-
-----------
86-
87-
Example of MongoDb database usage:
88-
89-
::
90-
91-
def test_docker_run_mongodb():
92-
mongo_container = MongoDbContainer("mongo:latest")
93-
with mongo_container as mongo:
94-
db = mongo.get_connection_client().test
95-
result = db.restaurants.insert_one(
96-
{
97-
"address": {
98-
"street": "2 Avenue",
99-
"zipcode": "10075",
100-
"building": "1480",
101-
"coord": [-73.9557413, 40.7720266]
102-
},
103-
"borough": "Manhattan",
104-
"cuisine": "Italian",
105-
"name": "Vella",
106-
"restaurant_id": "41704620"
107-
}
108-
)
109-
print(result.inserted_id)
110-
cursor = db.restaurants.find({"borough": "Manhattan"})
111-
for document in cursor:
112-
print(document)
113-
114-
Connection is made using pymongo package and MongoClient class.
115-
Alternatively, you can use get_connection_url method to use the driver that better fits for your use case.
116-
117-
Microsoft SQL Server
118-
--------------------
119-
120-
::
121-
122-
mssql = SqlServerContainer()
123-
124-
with mssql:
125-
e = sqlalchemy.create_engine(mssql.get_connection_url())
126-
result = e.execute("select @@VERSION")
127-
128-
It uses the Microsoft-provided Docker image and requires `ODBC Driver 17 for SQL Server
129-
<https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server>`_.
4+
Allows to spin up database images such as MySQL, PostgreSQL, MariaDB, Oracle XE, or MongoDb.
5+
6+
.. autoclass:: testcontainers.mysql.MySqlContainer
7+
.. autoclass:: testcontainers.mysql.MariaDbContainer
8+
.. autoclass:: testcontainers.postgres.PostgresContainer
9+
.. autoclass:: testcontainers.oracle.OracleDbContainer
10+
.. autoclass:: testcontainers.elasticsearch.ElasticSearchContainer
11+
.. autoclass:: testcontainers.mongodb.MongoDbContainer
12+
.. autoclass:: testcontainers.mssql.SqlServerContainer

‎docs/google-cloud-emulators.rst

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,2 @@
1-
Google Cloud Emulators
2-
======================
3-
4-
Allows to spin up google cloud emulators, such as PubSub.
5-
6-
PubSub example
7-
--------------
8-
9-
::
10-
11-
def test_docker_run_pubsub():
12-
config = PubSubContainer('google/cloud-sdk:latest')
13-
with config as pubsub:
14-
publisher = pubsub.get_publisher()
15-
topic_path = publisher.topic_path(pubsub.project, "my-topic")
16-
topic = publisher.create_topic(topic_path)
17-
18-
The example will spin up a Google Cloud PubSub emulator that you can use for integration tests. The :code:`pubsub` instance provides convenience methods :code:`get_publisher` and :code:`get_subscriber` to connect to the emulator without having to set the environment variable :code:`PUBSUB_EMULATOR_HOST`.
1+
.. automodule:: testcontainers.google
2+
:members: PubSubContainer

0 commit comments

Comments
 (0)