Xnat4Tests
==========
.. image:: https://github.com/australian-imaging-service/xnat4tests/actions/workflows/test.yml/badge.svg
:target: https://github.com/Australian-Imaging-Service/xnat4tests/actions/workflows/test.yml
.. image:: https://codecov.io/gh/australian-imaging-service/xnat4tests/branch/main/graph/badge.svg?token=UIS0OGPST7
:target: https://codecov.io/gh/australian-imaging-service/xnat4tests
.. image:: https://img.shields.io/pypi/v/xnat4tests.svg
:target: https://pypi.python.org/pypi/xnat4tests/
.. image:: https://img.shields.io/pypi/pyversions/xnat4tests.svg
:target: https://pypi.python.org/pypi/xnat4tests/
:alt: Supported Python versions
Xnat4Tests runs a basic XNAT repository instance in a single Docker to be
used for quick demonstrations on your workstation or integrated within test suites for
tools that use XNAT's REST API.
The XNAT container service plugin is installed by default and is configured to use
the same Docker host as the XNAT instance.
The ``home/logs``, ``home/work``, ``build``, ``archive``, ``prearchive`` directories are
mounted in from the host system from the ``$HOME/.xnat4tests/xnat_root/default`` directory
by default. This can be useful for debugging and can be used to replicate the environment
under which containers run in within XNAT's container service.
In addition to the ``start_xnat``, ``stop_xnat`` and ``restart_xnat`` functions, which control the life-cycle of
the XNAT instance, there is also a ``connect`` function that returns an XnatPy connection object to the test instance
Installation
------------
Docker needs to be installed on your system, see `Get Docker <https://docs.docker.com/get-docker/>`_
for details.
Xnat4Tests is available on PyPI so can be installed with
.. code-block:: bash
$ pip3 install xnat4tests
or include in your package's ``test_requires`` if you are writing Python tests.
Usage
-----
Command line interface
~~~~~~~~~~~~~~~~~~~~~~
A test XNAT instance can be launched using the CLI with
.. code-block:: bash
$ xnat4tests start
This will spin up an empty XNAT instance that can be accessed using the default admin
user account user='admin'/password='admin'. To add some sample data to play with you
can use the `add-data` command
.. code-block:: bash
$ xnat4tests start
$ xnat4tests add-data 'dummydicom'
or in a single line
.. code-block:: bash
$ xnat4tests start --with-data 'dummydicom'
By default, xnat4tests will create a configuration file at `$HOME/.xnat4tests/configs/default.yaml`.
The config file can be adapted to modify the names of the Docker images/containers used, the ports
the containers run on, and which directories are mounted into the container. Multiple
configurations can be used concurrently by saving the config file to a new location and
passing it to the base command, i.e.
.. code-block:: bash
$ xnat4tests --config /path/to/my/repo/xnat4tests-config.yaml start
To stop or restart the running container you can use ``xnat4tests stop`` and ``xnat4tests
restart`` commands, respectively.
Python API
~~~~~~~~~~
If you are developing Python applications you will typically want to use the API to
launch the XNAT instance using the `xnat4tests.start_xnat` function. An XnatPy connection
session object can be accessed using `xnat4tests.connect` and the instanced stopped
afterwards using `stop_xnat`.
.. code-block:: python
# Import xnat4tests functions
from xnat4tests import start_xnat, stop_xnat, connect, Config
config = Config.load("default")
# Launch the instance (NB: it takes quite while for an XNAT instance to start). If an existing
# container with the reserved name is already running it is returned instead
start_xnat(config)
# Connect to the XNAT instance using XnatPy and run some tests
with connect(config) as login:
PROJECT = 'MY_TEST_PROJECT'
SUBJECT = 'MYSUBJECT'
SESSION = 'MYSESSION'
login.put(f'/data/archive/projects/MY_TEST_PROJECT')
# Create subject
xsubject = login.classes.SubjectData(label=SUBJECT,
parent=login.projects[PROJECT])
# Create session
login.classes.MrSessionData(label=SESSION, parent=xsubject)
assert [p.name for p in (config.xnat_root_dir / "archive").iterdir()] == [PROJECT]
# Remove the container after you are done (not strictly necessary). To avoid
# having to wait for XNAT to restart each time before you run your tests, you can
# skip this line and start_xnat will attempt to use the instance that is already
# running
stop_xnat(config)
Alternatively, if you are using Pytest then you can set up the connection as
a fixture in your ``conftest.py``, e.g.
.. code-block:: python
import tempfile
from pathlib import Path
from xnat4tests import start_xnat, stop_xnat, connect, Config
@pytest.fixture(scope="session")
def xnat_config():
tmp_dir = Path(tempfile.mkdtemp())
return Config(
xnat_root_dir=tmp_dir,
xnat_port=9999,
docker_image="myrepo_xnat4tests",
docker_container="myrepo_xnat4tests",
build_args={
"xnat_version": "1.8.5",
"xnat_cs_plugin_version": "3.2.0",
},
)
@pytest.fixture(scope="session")
def xnat_uri(xnat_config):
xnat4tests.start_xnat(xnat_config)
xnat4tests.add_data("dummydicom")
yield xnat_config.xnat_uri
xnat4tests.stop_xnat(xnat_config)
Raw data
{
"_id": null,
"home_page": "https://github.com/australian-imaging-service/xnat4tests",
"name": "xnat4tests",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "repository analysis neuroimaging workflows pipelines",
"author": "Thomas G. Close",
"author_email": "tom.g.close@gmail.com",
"download_url": "",
"platform": null,
"description": "Xnat4Tests\n==========\n.. image:: https://github.com/australian-imaging-service/xnat4tests/actions/workflows/test.yml/badge.svg\n :target: https://github.com/Australian-Imaging-Service/xnat4tests/actions/workflows/test.yml\n.. image:: https://codecov.io/gh/australian-imaging-service/xnat4tests/branch/main/graph/badge.svg?token=UIS0OGPST7\n :target: https://codecov.io/gh/australian-imaging-service/xnat4tests\n.. image:: https://img.shields.io/pypi/v/xnat4tests.svg\n :target: https://pypi.python.org/pypi/xnat4tests/\n.. image:: https://img.shields.io/pypi/pyversions/xnat4tests.svg\n :target: https://pypi.python.org/pypi/xnat4tests/\n :alt: Supported Python versions\n\n\nXnat4Tests runs a basic XNAT repository instance in a single Docker to be\nused for quick demonstrations on your workstation or integrated within test suites for\ntools that use XNAT's REST API. \n\nThe XNAT container service plugin is installed by default and is configured to use\nthe same Docker host as the XNAT instance.\n\nThe ``home/logs``, ``home/work``, ``build``, ``archive``, ``prearchive`` directories are\nmounted in from the host system from the ``$HOME/.xnat4tests/xnat_root/default`` directory\nby default. This can be useful for debugging and can be used to replicate the environment\nunder which containers run in within XNAT's container service.\n\nIn addition to the ``start_xnat``, ``stop_xnat`` and ``restart_xnat`` functions, which control the life-cycle of\nthe XNAT instance, there is also a ``connect`` function that returns an XnatPy connection object to the test instance\n\n\nInstallation\n------------\n\nDocker needs to be installed on your system, see `Get Docker <https://docs.docker.com/get-docker/>`_\nfor details.\n\nXnat4Tests is available on PyPI so can be installed with\n\n.. code-block:: bash\n\n $ pip3 install xnat4tests\n\nor include in your package's ``test_requires`` if you are writing Python tests.\n\nUsage\n-----\n\nCommand line interface\n~~~~~~~~~~~~~~~~~~~~~~\n\nA test XNAT instance can be launched using the CLI with\n\n.. code-block:: bash\n\n $ xnat4tests start\n\nThis will spin up an empty XNAT instance that can be accessed using the default admin\nuser account user='admin'/password='admin'. To add some sample data to play with you\ncan use the `add-data` command\n\n.. code-block:: bash\n\n $ xnat4tests start\n $ xnat4tests add-data 'dummydicom'\n\nor in a single line\n\n.. code-block:: bash\n\n $ xnat4tests start --with-data 'dummydicom'\n\nBy default, xnat4tests will create a configuration file at `$HOME/.xnat4tests/configs/default.yaml`.\nThe config file can be adapted to modify the names of the Docker images/containers used, the ports\nthe containers run on, and which directories are mounted into the container. Multiple\nconfigurations can be used concurrently by saving the config file to a new location and\npassing it to the base command, i.e.\n\n.. code-block:: bash\n\n $ xnat4tests --config /path/to/my/repo/xnat4tests-config.yaml start\n\nTo stop or restart the running container you can use ``xnat4tests stop`` and ``xnat4tests\nrestart`` commands, respectively.\n\n\nPython API\n~~~~~~~~~~\n\nIf you are developing Python applications you will typically want to use the API to\nlaunch the XNAT instance using the `xnat4tests.start_xnat` function. An XnatPy connection\nsession object can be accessed using `xnat4tests.connect` and the instanced stopped\nafterwards using `stop_xnat`.\n\n.. code-block:: python\n\n # Import xnat4tests functions\n from xnat4tests import start_xnat, stop_xnat, connect, Config\n\n config = Config.load(\"default\")\n\n # Launch the instance (NB: it takes quite while for an XNAT instance to start). If an existing\n # container with the reserved name is already running it is returned instead\n start_xnat(config)\n\n # Connect to the XNAT instance using XnatPy and run some tests\n with connect(config) as login:\n PROJECT = 'MY_TEST_PROJECT'\n SUBJECT = 'MYSUBJECT'\n SESSION = 'MYSESSION'\n\n login.put(f'/data/archive/projects/MY_TEST_PROJECT')\n\n # Create subject\n xsubject = login.classes.SubjectData(label=SUBJECT,\n parent=login.projects[PROJECT])\n # Create session\n login.classes.MrSessionData(label=SESSION, parent=xsubject)\n\n assert [p.name for p in (config.xnat_root_dir / \"archive\").iterdir()] == [PROJECT]\n\n # Remove the container after you are done (not strictly necessary). To avoid\n # having to wait for XNAT to restart each time before you run your tests, you can\n # skip this line and start_xnat will attempt to use the instance that is already\n # running\n stop_xnat(config)\n\nAlternatively, if you are using Pytest then you can set up the connection as\na fixture in your ``conftest.py``, e.g.\n\n.. code-block:: python\n\n import tempfile\n from pathlib import Path\n from xnat4tests import start_xnat, stop_xnat, connect, Config\n\n @pytest.fixture(scope=\"session\")\n def xnat_config():\n tmp_dir = Path(tempfile.mkdtemp())\n return Config(\n xnat_root_dir=tmp_dir,\n xnat_port=9999,\n docker_image=\"myrepo_xnat4tests\",\n docker_container=\"myrepo_xnat4tests\",\n build_args={\n \"xnat_version\": \"1.8.5\",\n \"xnat_cs_plugin_version\": \"3.2.0\",\n },\n )\n\n @pytest.fixture(scope=\"session\")\n def xnat_uri(xnat_config):\n xnat4tests.start_xnat(xnat_config)\n xnat4tests.add_data(\"dummydicom\")\n yield xnat_config.xnat_uri\n xnat4tests.stop_xnat(xnat_config)\n",
"bugtrack_url": null,
"license": "CC0",
"summary": "Creates basic XNAT instance for API tests",
"version": "0.3.8",
"project_urls": {
"Homepage": "https://github.com/australian-imaging-service/xnat4tests"
},
"split_keywords": [
"repository",
"analysis",
"neuroimaging",
"workflows",
"pipelines"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "954e6519c67c82e0069805127061dadeb9f075743cfa92e13d496bda0d742f2e",
"md5": "e0e6fc1372782901903730a8ba923099",
"sha256": "bca94cd5c89280547b04bde8c94f0d9bc69e211f2a48f8798d74583263192296"
},
"downloads": -1,
"filename": "xnat4tests-0.3.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0e6fc1372782901903730a8ba923099",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20798,
"upload_time": "2023-08-09T02:59:03",
"upload_time_iso_8601": "2023-08-09T02:59:03.862200Z",
"url": "https://files.pythonhosted.org/packages/95/4e/6519c67c82e0069805127061dadeb9f075743cfa92e13d496bda0d742f2e/xnat4tests-0.3.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-09 02:59:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "australian-imaging-service",
"github_project": "xnat4tests",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "xnat4tests"
}
JSON
