Commit e9f79d0d authored by Mark Hymers's avatar Mark Hymers

New upstream version 0.3

include pytest_mpi/
include pypi-intro.rst
include LICENSE.txt
recursive-include docs *
recursive-exclude docs/_build *
include doc-requirements.txt
include test-requirements.txt
recursive-include tests *.py
include pylintrc
include tox.ini
exclude TODO
prune **/__pycache__
prune **/*.pyc
prune **/*.swp
prune **/*.swo
Metadata-Version: 1.1
Name: pytest-mpi
Version: 0.3
Summary: pytest plugin to collect information from tests
Author: James Tocknell
License: 3-clause BSD
Description: `pytest_mpi` is a plugin for pytest providing some useful tools when running
tests under MPI, and testing MPI-related code.
To run a test only when using MPI, use the `pytest.mark.mpi` marker like:
def test_mpi():
Further documentation can be found at `<>`_.
Bug reports and suggestions should be filed at
|Documentation Status| |Build Status| |Coverage Status|
.. |Documentation Status| image::
.. |Build Status| image::
.. |Coverage Status| image::
Keywords: pytest testing
Platform: UNKNOWN
Classifier: Framework :: Pytest
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
[![Documentation Status](](
[![Build Status](](
[![Coverage Status](](
[![Supported versions](](
[![Supported implemntations](](
`pytest_mpi` is a plugin for pytest providing some useful tools when running
tests under MPI, and testing MPI-related code.
To run a test only when using MPI, use the `pytest.mark.mpi` marker like:
def test_mpi():
Further documentation can be found at [](
Bug reports and suggestions should be filed at
# Minimal makefile for Sphinx documentation
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
\ No newline at end of file
* Fixed pylint failures
* Added testing of examples in documentation
* Added proper tests
* Fix bugs found via tests
* Add proper documentation of features
* Display more MPI related information on test run
* Add `mpi_skip` and `mpi_xfail` markers
* Add `mpi_tmpdir` and `mpi_tmp_path`
* Fix plugin as the pytest command line parsing logic needs to be outside main
plugin class
Initial version
# -*- coding: utf-8 -*-
# Configuration file for the Sphinx documentation builder.
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = u'pytest-mpi'
copyright = u'2019, James Tocknell'
author = u'James Tocknell'
import sys
import os
sys.path.insert(0, os.path.abspath('..'))
import pytest_mpi
# The short X.Y version
version = '.'.join(pytest_mpi.__version__.split(".")[0:2])
# The full version, including alpha/beta/rc tags.
release = pytest_mpi.__version__
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'pytest-mpidoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
# Latex figure (float) alignment
# 'figure_align': 'htbp',
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'pytest-mpi.tex', u'pytest-mpi Documentation',
u'James Tocknell', 'manual'),
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pytest-mpi', u'pytest-mpi Documentation',
[author], 1)
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'pytest-mpi', u'pytest-mpi Documentation',
author, 'pytest-mpi', 'One line description of project.',
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
# epub_identifier = ''
# A unique identification for the text.
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'': None}
from doctest import ELLIPSIS
import pytest
from sybil import Sybil
from sybil.parsers.codeblock import CodeBlockParser
from sybil.parsers.doctest import DocTestParser, FIX_BYTE_UNICODE_REPR
from sybil.parsers.skip import skip
pytest_collect_file = Sybil(
.. autofunction:: pytest_mpi.mpi_file_name
.. autofunction:: pytest_mpi.mpi_tmp_path
.. autofunction:: pytest_mpi.mpi_tmpdir
.. pytest-mpi documentation master file, created by
sphinx-quickstart on Wed Jun 26 22:34:19 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to pytest-mpi's documentation!
`pytest-mpi` provides a number of things to assist with using pytest with
MPI-using code, specifically:
* Displaying of the current MPI configuration (e.g. the MPI version, the
number of processes)
* Sharing temporary files/folders across the MPI processes
* Markers which allow for skipping or xfailing tests based on whether the
tests are being run under MPI
Further features will be added in the future, and contribution of features is
very much welcomed.
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
set BUILDDIR=_build
if "%1" == "" goto help
if errorlevel 9009 (
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.If you don't have Sphinx installed, grab it from
exit /b 1
goto end
.. py:function:: pytest.mark.mpi(min_size=None)
Mark that this test must be run under MPI.
:keyword int min_size:
Specify that this test requires at least `min_size` processes to run. If
there are insufficient processes, skip this test.
For example:
.. code-block:: python
import pytest
def test_mpi_feature():
.. py:function:: pytest.mark.mpi_skip
Mark that this test should be skipped when run under MPI.
.. py:function:: pytest.mark.mpi_xfail
Mark that this test should be xfailed when run under MPI.
The important thing to remember is that `pytest-mpi` assists with running tests
when `pytest` is run under MPI, rather than launching `pytest` under MPI. To
actually run the tests under MPI, you will want to run something like::
$ mpirun -n 2 python -m pytest --with-mpi
Note that by default the MPI tests are not run—this makes it easy to run the
non-MPI parts of a test suite without having to worry about installing MPI and
An simple test using the `mpi` marker managed by `pytest-mpi` is:
.. code-block:: python
import pytest
def test_size():
from mpi4py import MPI
assert comm.size > 0
This test will be automatically be skipped unless `--with-mpi` is used. We can
also specify a minimum number of processes required to run the test:
.. code-block:: python
import pytest
def test_size():
from mpi4py import MPI
assert comm.size >= 2
There are also `mpi_skip`, for when a test should not be run under MPI (e.g. it
causes a lockup or segmentation fault), and `mpi_xfail`, for when a test should
succeed when run normally, but fail when run under MPI.
# Specify a configuration file.
# Python code to execute, usually for sys.path manipulation such as
# pygtk.require().
# Add files or directories to the blacklist. They should be base names, not
# paths.
# Pickle collected data for later comparisons.
# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
# Set the output format. Available formats are text, parseable, colorized, msvs
# (visual studio) and html. You can also give a reporter class, eg
# mypackage.mymodule.MyReporterClass.
# Put messages in a separate file for each module / package specified on the
# command line instead of printing them on stdout. Reports (if any) will be
# written in a file name "pylint_global.[txt|html]".
# Tells whether to display a full report or only the messages
# Python expression which should return a note less than 10 (10 is the highest
# note). You have access to the variables errors warning, statement which
# respectively contain the number of errors / warnings messages and the total
# number of statements analyzed. This is used by the global evaluation report
# (RP0004).
evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
# Template used to display messages. This is a python new-style format string
# used to format the message information. See doc for all details
# Enable the message, report, category or checker with the given id(s). You can
# either give multiple identifier separated by comma (,) or put this option
# multiple time. See also the "--disable" option for examples.
# Disable the message, report, category or checker with the given id(s). You
# can either give multiple identifiers separated by comma (,) or put this
# option multiple times (only on the command line, not in the configuration
# file where it should appear only once).You can also use "--disable=all" to
# disable everything first and then reenable specific checks. For example, if
# you want to run only the similarities checker, you can use "--disable=all
# --enable=similarities". If you want to run only the classes checker, but have
# no Warning level messages displayed, use"--disable=all --enable=classes
# --disable=W"
# Minimum lines number of a similarity.
# Ignore comments when computing similarities.
# Ignore docstrings when computing similarities.
# Ignore imports when computing similarities.
# List of builtins function names that should not be used, separated by a comma
# Good variable names which should always be accepted, separated by a comma
# Bad variable names which should always be refused, separated by a comma
# Colon-delimited sets of names that determine each other's naming style when
# the name regexes allow several styles.
# Include a hint for the correct naming format with invalid-name
# Regular expression matching correct module names
# Naming hint for module names
# Regular expression matching correct method names
# Naming hint for method names
# Regular expression matching correct variable names
# Naming hint for variable names
# Regular expression matching correct constant names
# Naming hint for constant names
# Regular expression matching correct argument names
# Naming hint for argument names
# Regular expression matching correct inline iteration names
# Naming hint for inline iteration names
# Regular expression matching correct attribute names
# Naming hint for attribute names
# Regular expression matching correct class names
# Naming hint for class names
# Regular expression matching correct function names
# Naming hint for function names
# Regular expression matching correct class attribute names
# Naming hint for class attribute names
# Regular expression which should only match function or class names that do
# not require a docstring.
# Minimum line length for functions/classes that require docstrings, shorter
# ones are exempt.
# Logging modules to check that the string format arguments are in logging