Commit e9f79d0d authored by Mark Hymers's avatar Mark Hymers

New upstream version 0.3

parents
include versioneer.py pytest_mpi/_version.py
include README.md
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
Home-page: https://pytest-mpi.readthedocs.io
Author: James Tocknell
Author-email: aragilar@gmail.com
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:
::
@pytest.mark.mpi
def test_mpi():
pass
Further documentation can be found at `<https://pytest-mpi.readthedocs.io>`_.
Bug reports and suggestions should be filed at
`<https://github.com/aragilar/pytest-mpi/issues>`_.
|Documentation Status| |Build Status| |Coverage Status|
.. |Documentation Status| image:: https://readthedocs.org/projects/pytest-mpi/badge/?version=latest
:target: http://pytest-mpi.readthedocs.org/en/latest/?badge=latest
.. |Build Status| image:: https://travis-ci.org/aragilar/pytest-mpi.svg?branch=master
:target: https://travis-ci.org/aragilar/pytest-mpi
.. |Coverage Status| image:: https://codecov.io/github/aragilar/pytest-mpi/coverage.svg?branch=master
:target: https://codecov.io/github/aragilar/pytest-mpi?branch=master
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](https://readthedocs.org/projects/pytest-mpi/badge/?version=latest)](http://pytest-mpi.readthedocs.org/en/latest/?badge=latest)
[![Build Status](https://travis-ci.org/aragilar/pytest-mpi.svg?branch=master)](https://travis-ci.org/aragilar/pytest-mpi)
[![Coverage Status](https://codecov.io/github/aragilar/pytest-mpi/coverage.svg?branch=master)](https://codecov.io/github/aragilar/pytest-mpi?branch=master)
[![Version](https://img.shields.io/pypi/v/pytest-mpi.svg)](https://pypi.python.org/pypi/pytest-mpi/)
[![License](https://img.shields.io/pypi/l/pytest-mpi.svg)](https://pypi.python.org/pypi/pytest-mpi/)
[![Wheel](https://img.shields.io/pypi/wheel/pytest-mpi.svg)](https://pypi.python.org/pypi/pytest-mpi/)
[![Format](https://img.shields.io/pypi/format/pytest-mpi.svg)](https://pypi.python.org/pypi/pytest-mpi/)
[![Supported versions](https://img.shields.io/pypi/pyversions/pytest-mpi.svg)](https://pypi.python.org/pypi/pytest-mpi/)
[![Supported implemntations](https://img.shields.io/pypi/implementation/pytest-mpi.svg)](https://pypi.python.org/pypi/pytest-mpi/)
[![PyPI](https://img.shields.io/pypi/status/pytest-mpi.svg)](https://pypi.python.org/pypi/pytest-mpi/)
`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:
```python
@pytest.mark.mpi
def test_mpi():
pass
```
Further documentation can be found at [https://pytest-mpi.readthedocs.io](https://pytest-mpi.readthedocs.io).
Bug reports and suggestions should be filed at
[https://github.com/aragilar/pytest-mpi/issues](https://github.com/aragilar/pytest-mpi/issues).
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.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
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
Changelog
=========
0.3
---
* Fixed pylint failures
* Added testing of examples in documentation
* Added proper tests
* Fix bugs found via tests
0.2
---
* 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`
0.1.1
-----
* Fix plugin as the pytest command line parsing logic needs to be outside main
plugin class
0.1
---
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:
# http://www.sphinx-doc.org/en/master/config
# -- 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 = [
'sphinx.ext.intersphinx',
'sphinx.ext.coverage',
'sphinx.ext.autodoc',
]
# 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.',
'Miscellaneous'),
]
# -- 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 = {'https://docs.python.org/': 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(
parsers=[
DocTestParser(optionflags=ELLIPSIS|FIX_BYTE_UNICODE_REPR),
CodeBlockParser(),
skip,
],
pattern='*.rst',
).pytest()
Fixtures
========
.. 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:
usage
markers
fixtures
changelog
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd
Markers
=======
.. 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
@pytest.mark.mpi(minsize=4)
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.
Usage
=====
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
mpi4py.
An simple test using the `mpi` marker managed by `pytest-mpi` is:
.. code-block:: python
import pytest
@pytest.mark.mpi
def test_size():
from mpi4py import MPI
comm = MPI.COMM_WORLD
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
@pytest.mark.mpi(min_size=2)
def test_size():
from mpi4py import MPI
comm = MPI.COMM_WORLD
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.
[MASTER]
# Specify a configuration file.
#rcfile=
# Python code to execute, usually for sys.path manipulation such as
# pygtk.require().
#init-hook=
# Add files or directories to the blacklist. They should be base names, not
# paths.
ignore=CVS,_version.py
# Pickle collected data for later comparisons.
persistent=yes
# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
load-plugins=
[REPORTS]
# 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.
output-format=colorized
# 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]".
files-output=no
# Tells whether to display a full report or only the messages
reports=no
# 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
#msg-template=
[MESSAGES CONTROL]
# 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.
#enable=
# 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"
disable=useless-object-inheritance,no-self-use,import-outside-toplevel,no-member
[SIMILARITIES]
# Minimum lines number of a similarity.
min-similarity-lines=4
# Ignore comments when computing similarities.
ignore-comments=yes
# Ignore docstrings when computing similarities.
ignore-docstrings=yes
# Ignore imports when computing similarities.
ignore-imports=no
[BASIC]
# List of builtins function names that should not be used, separated by a comma
bad-functions=map,filter,apply
# Good variable names which should always be accepted, separated by a comma
good-names=i,j,k
# Bad variable names which should always be refused, separated by a comma
bad-names=foo,bar,baz,toto,tutu,tata
# Colon-delimited sets of names that determine each other's naming style when
# the name regexes allow several styles.
name-group=
# Include a hint for the correct naming format with invalid-name
include-naming-hint=no
# Regular expression matching correct module names
module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
# Naming hint for module names
module-name-hint=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
# Regular expression matching correct method names
method-rgx=[a-z_][a-z0-9_]{2,30}$
# Naming hint for method names
method-name-hint=[a-z_][a-z0-9_]{2,30}$
# Regular expression matching correct variable names
variable-rgx=[a-z_][a-z0-9_]{2,30}$
# Naming hint for variable names
variable-name-hint=[a-z_][a-z0-9_]{2,30}$
# Regular expression matching correct constant names
const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__))$
# Naming hint for constant names
const-name-hint=(([A-Z_][A-Z0-9_]*)|(__.*__))$
# Regular expression matching correct argument names
argument-rgx=[a-z_][a-z0-9_]{2,30}$
# Naming hint for argument names
argument-name-hint=[a-z_][a-z0-9_]{2,30}$
# Regular expression matching correct inline iteration names
inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$
# Naming hint for inline iteration names
inlinevar-name-hint=[A-Za-z_][A-Za-z0-9_]*$
# Regular expression matching correct attribute names
attr-rgx=[a-z_][a-z0-9_]{2,30}$
# Naming hint for attribute names
attr-name-hint=[a-z_][a-z0-9_]{2,30}$
# Regular expression matching correct class names
class-rgx=[A-Z_][a-zA-Z0-9]+$
# Naming hint for class names
class-name-hint=[A-Z_][a-zA-Z0-9]+$
# Regular expression matching correct function names
function-rgx=[a-z_][a-z0-9_]{2,30}$
# Naming hint for function names
function-name-hint=[a-z_][a-z0-9_]{2,30}$
# Regular expression matching correct class attribute names
class-attribute-rgx=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
# Naming hint for class attribute names
class-attribute-name-hint=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
# Regular expression which should only match function or class names that do
# not require a docstring.
no-docstring-rgx=__.*__
# Minimum line length for functions/classes that require docstrings, shorter
# ones are exempt.
docstring-min-length=-1
[LOGGING]
# Logging modules to check that the string format arguments are in logging
# function parameter format
logging-modules=logging
[MISCELLANEOUS]
# List of note tags to take in consideration, separated by a comma.
notes=FIXME,XXX,TODO
[TYPECHECK]
# Tells whether missing members accessed in mixin class should be ignored. A
# mixin class is detected if its name ends with "mixin" (case insensitive).
ignore-mixin-members=yes
# List of module names for which member attributes should not be checked
# (useful for modules/projects where namespaces are manipulated during runtime
# and thus existing member attributes cannot be deduced by static analysis
#ignored-modules=numpy,scikits.odes.sundials.cvode
# List of classes names for which member attributes should not be checked
# (useful for classes with attributes dynamically set).
#ignored-classes=SQLObject
# List of members which are set dynamically and missed by pylint inference
# system, and so shouldn't trigger E0201 when accessed. Python regular
# expressions are accepted.
generated-members=REQUEST,acl_users,aq_parent
[FORMAT]
# Maximum number of characters on a single line.
max-line-length=80
# Regexp for a line that is allowed to be longer than the limit.
ignore-long-lines=^\s*(# )?<?https?://\S+>?$
# Allow the body of an if to be on the same line as the test if there is no
# else.
single-line-if-stmt=no
# List of optional constructs for which whitespace checking is disabled
no-space-check=trailing-comma,dict-separator
# Maximum number of lines in a module
max-module-lines=1000