dockerctx 2026.1.1__py3-none-any.whl

dockerctx/__init__.py

@@ -0,0 +1,199 @@
+""" A context manager for a docker container. """
+from __future__ import division, print_function
+
+
+import socket
+from contextlib import contextmanager
+from importlib.metadata import PackageNotFoundError, version
+import uuid
+import logging
+import time
+import typing
+import docker
+
+
+try:
+    __version__ = version('dockerctx')
+except PackageNotFoundError:
+    __version__ = '0.0.0'
+__all__ = ['new_container']
+logger = logging.getLogger('dockerctx')
+
+
+@contextmanager
+def new_container(
+        image_name,
+        new_container_name=lambda: uuid.uuid4().hex,
+        ports=None,
+        tmpfs=None,
+        ready_test=None,
+        docker_api_version='auto',
+        persist=lambda: False,
+        **kwargs):
+    """Start a docker container, and kill+remove when done.
+
+    :param new_container_name: The container name. By default, a UUID will be used.
+        If a callable, the result must be a str.
+    :type new_container_name: str | callable
+    :param ports: The list of port mappings to configure on the docker
+        container. The format is the same as that used in the `docker`
+        package, e.g. `ports={'5432/tcp': 60011}`
+    :type ports: typing.Dict[str, int]
+    :param tmpfs: When creating a container you can specify paths to be mounted
+        with tmpfs. It can be a list or a dictionary to configure on the docker
+        container. If it's a list, each item is a string specifying the path and
+        (optionally) any configuration for the mount, e.g. `tmpfs={'/mnt/vol2': '',
+        '/mnt/vol1': 'size=3G,uid=1000'}`
+    :type tmpfs: typing.Dict[str, str]
+    :param ready_test: A function to run to verify whether the container is "ready"
+        (in some sense) before yielding the container back to the caller. An example
+        of such a test is the `accepting_connections` function in the this module,
+        which will try repeatedly to connect to a socket, until either successfuly,
+        or a max timeout is reached. Use functools.partial to wrap up the args.
+    :type ready_test: typing.Callable[[], bool]
+    :param privileged: a privileged container is given access to all devices on
+        the host as well as set some configuration in AppArmor or SELinux to allow
+        the container nearly all the same access to the host as processes running
+        outside containers on the host.
+    :type persist: typing.Callable[[], bool]
+    :param persist: If True, the docker container will NOT be destroyed
+        during exit. This is sometimes useful if you want to keep a container
+        around, but only if tests fail. (That's why it's a callable: it only
+        gets called during the "exit" phase of the context manager).
+    :param kwargs: These extra keyword arguments will be passed through to the
+        `client.containers.run()` call.  One of the more commons ones is to pass
+        a custom command through.
+
+    """
+    _ = new_container_name
+    name = str(_() if callable(_) else _)
+    client = docker.from_env(version=docker_api_version)
+
+    logger.info('New container: %s', name)
+    container = client.containers.run(
+        image_name, name=name, tmpfs=tmpfs, detach=True, ports=ports,
+        **kwargs
+    )
+    try:
+        logger.info('Waiting for container to be ready')
+        if ready_test and not ready_test():
+            raise ConnectionError(
+                'Container {} not ready fast enough.'.format(name)
+            )
+        yield container
+    finally:
+        if persist():
+            logger.info('Leaving container up.')
+        else:
+            logger.info('Stopping container %s', name)
+            try:
+                container.stop(timeout=1)
+            except docker.errors.APIError as e:
+                logger.error('Error stopping container: %s', e)
+
+            logger.info('Removing container %s', name)
+            try:
+                container.remove(force=True)
+            except docker.errors.APIError as e:
+                logger.error('Error removing container: %s', e)
+
+
+def accepting_connections(host, port, timeout=20):
+    """Try to make a socket connection to `(host, port)`
+
+    I'll try every 200 ms, and eventually give up after `timeout`.
+
+    :type host: str
+    :type port: int
+    :type timeout: int
+    :return: True for successful connection, False otherwise
+    :rtype: bool
+    """
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        try:
+            # s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            s = socket.create_connection((host, port))
+            logger.debug('Connected!')
+            s.close()
+            return True
+        except socket.error as ex:
+            logger.debug("Connection failed with errno %s: %s",
+                         ex.errno, ex.strerror)
+        time.sleep(0.2)
+    return False
+
+
+def pg_ready(host, port, dbuser='postgres', dbpass='password', dbname='postgres',
+             timeout=20, poll_freq=0.2):
+    """Wait until a postgres instance is ready to receive connections.
+
+    .. note::
+
+        This requires psycopg2 to be installed.
+
+    :type host: str
+    :type port: int
+    :type timeout: float
+    :type poll_freq: float
+    """
+    import psycopg2
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        try:
+            conn = psycopg2.connect(
+                "host={host} port={port} user={dbuser} password={dbpass} "
+                "dbname={dbname}".format(**vars())
+            )
+            logger.debug('Connected successfully.')
+            conn.close()
+            return True
+        except psycopg2.OperationalError as ex:
+            logger.debug("Connection failed: {0}".format(ex));
+        time.sleep(poll_freq)
+
+    logger.error('Postgres readiness check timed out.')
+    return False
+
+
+@contextmanager
+def session_scope(session_cls):
+    """Provide a transactional scope around a series of operations.
+
+    .. note::
+
+        This requires SQLAlchemy to be installed.
+
+    :type: sqlalchemy.orm.Session
+    """
+    session = session_cls()
+    try:
+        logger.debug('Yielding session')
+        yield session
+        logger.debug('Committing session')
+        session.commit()
+    except:
+        logger.exception('Error detected, rolling back session')
+        session.rollback()
+        raise
+    finally:
+        logger.debug('Closing session')
+        session.close()
+
+
+def get_open_port():
+    """Return a currently-unused local network TCP port number
+
+    This is extremely handy when running unit tests because you may
+    not always be able to get the port of your choice, especially
+    in a continuous-integration context.
+
+    :return: TCP port number
+    :rtype: int
+    """
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.bind(('', 0))  # Using zero means the OS assigns one
+    address_info = s.getsockname()
+    port = int(address_info[1])
+    s.close()
+    return port

dockerctx-2026.1.1.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: dockerctx
+Version: 2026.1.1
+Summary: A context manager for a docker container.
+Author: Caleb Hattingh
+Author-email: Caleb Hattingh <caleb.hattingh@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Dist: docker
+Requires-Dist: psycopg2-binary
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/cjrh/dockerctx
+Description-Content-Type: text/x-rst
+
+.. image:: https://github.com/cjrh/dockerctx/workflows/Python%20application/badge.svg
+    :target: https://github.com/cjrh/dockerctx/actions
+
+.. image:: https://coveralls.io/repos/github/cjrh/dockerctx/badge.svg?branch=master
+    :target: https://coveralls.io/github/cjrh/dockerctx?branch=master
+
+.. image:: https://img.shields.io/pypi/pyversions/dockerctx.svg
+    :target: https://pypi.python.org/pypi/dockerctx
+
+.. image:: https://img.shields.io/github/tag/cjrh/dockerctx.svg
+    :target: https://github.com/cjrh/dockerctx
+
+.. image:: https://img.shields.io/pypi/v/dockerctx.svg
+    :target: https://img.shields.io/pypi/v/dockerctx.svg
+
+dockerctx
+=========
+
+*dockerctx* is a context manager for managing the lifetime of a docker container.
+
+The main use case is for setting up scaffolding for running tests, where you want
+something a little broader than *unit tests*, but less heavily integrated than,
+say, what you might write using `Robot framework`_.
+
+.. _Robot framework: http://robotframework.org/
+
+Install
+-------
+
+.. code-block:: bash
+
+    $ pip install dockerctx
+
+
+The development-specific requirements will be installed automatically.
+
+.. _flit: https://flit.readthedocs.io/en/latest/
+
+Demo
+----
+
+This is taken from one of the tests:
+
+.. code-block:: python3
+
+    import time
+    import redis
+    import pytest
+    from dockerctx import new_container
+
+    # First make a pytest fixture
+
+    @pytest.fixture(scope='function')
+    def f_redis():
+
+        # This is the new thing! It's pretty clear.  The `ready_test` provides
+        # a way to customize what "ready" means for each container. Here,
+        # we simply pause for a bit.
+
+        with new_container(
+                image_name='redis:latest',
+                ports={'6379/tcp': 56379},
+                ready_test=lambda: time.sleep(0.5) or True) as container:
+            yield container
+
+    # Here is the test.  Since the fixture is at the "function" level, a fully
+    # new Redis container will be created for each test that uses this fixture.
+    # After the test completes, the container will be removed.
+
+    def test_redis_a(f_redis):
+        # The container object comes from the `docker` python package. Here we
+        # access only the "name" attribute, but there are many others.
+        print('Container %s' % f_redis.name)
+        r = redis.StrictRedis(host='localhost', port=56379, db=0)
+        r.set('foo', 'bar')
+        assert r.get('foo') == b'bar'
+
+Note that a brand new Redis container is created here, used within the
+context of the context manager (which is wrapped into a *pytest* fixture
+here), and then the container is destroyed after the context manager
+exits.
+
+
+In the src, there is another, much more elaborate test which
+
+#. runs a *postgres* container;
+#. waits for postgres to begin accepting connections;
+#. creates a database;
+#. creates tables (using the SQLAlchemy_ ORM);
+#. performs database operations;
+#. tears down and removes the container afterwards.
+
+.. _SQLAlchemy: http://www.sqlalchemy.org/

dockerctx-2026.1.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+dockerctx/__init__.py,sha256=pH44R2OBJ1mga94ySwlQjyiCfUAg0YoGPlWLnBQkkqQ,6846
+dockerctx-2026.1.1.dist-info/licenses/LICENSE,sha256=sMyqgCurQZSqNZRvfh_jQxYKkxjHekuekMaN0IdlrcU,1071
+dockerctx-2026.1.1.dist-info/WHEEL,sha256=f5fWSvWsg5Knq5GWa6t1nJIug0Tqo69GqAWD_9LbBKw,81
+dockerctx-2026.1.1.dist-info/METADATA,sha256=FRno6NpgEL-Ic98BSqE_d_DBnviVSvW5TkbsCH3wpII,3922
+dockerctx-2026.1.1.dist-info/RECORD,,

dockerctx-2026.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.16
+Root-Is-Purelib: true
+Tag: py3-none-any

dockerctx-2026.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Caleb Hattingh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.