“create” ReadMe

The MSL package that is created by running the msl create command contains two scripts to help make development easier: setup.py and condatests.py.

setup.py

The setup.py file (that is created by running msl create) includes additional commands that can be used to run unit tests and to create the documentation for your MSL package.

Note

The Python packages that are required to execute the following commands (e.g., pytest and sphinx) are automatically installed (into the .eggs directory) if they are not already installed in your environment. Therefore, the first time that you run the following commands it will take longer to finish executing the command because these packages (and their own dependencies) need to be downloaded then installed. If you prefer to install these packages directly into your environment you can run conda install pytest pytest-cov pytest-runner sphinx sphinx_rtd_theme, or if you are using pip as your package manager then replace conda with pip.

The following command will run all test modules that pytest finds as well as testing all the example code that is located within the docstrings of the source code and in the .rst files in the docs/ directory. To modify the options that pytest will use to run the tests you can edit the [tool:pytest] section in setup.cfg. A coverage report is created in the htmlcov/index.html file. This report provides an overview of which parts of the code have been executed during the tests.

python setup.py tests

Warning

pytest can only load one configuration file and uses the following search order to find that file:

  1. pytest.ini - used even if it does not contain a [pytest] section

  2. tox.ini - must contain a [pytest] section to be used

  3. setup.cfg - must contain a [tool:pytest] section to be used

See the configuration file section for an example if you want to run pytest with custom options without modifying any of these configuration files.

Create the documentation files, uses sphinx-build. The documentation can be viewed by opening docs/_build/html/index.html

python setup.py docs

Automatically create the API documentation from the docstrings in the source code, uses sphinx-apidoc. The files are saved to docs/_autosummary

python setup.py apidocs

Attention

By default, the docs/_autosummary directory that is created by running this command is automatically generated (overwrites existing files). As such, it is excluded from the repository (i.e., this directory is specified in the .gitignore file). If you want to keep the files located in docs/_autosummary you should rename the directory to, for example, docs/_api and then the changes made to the files in the docs/_api directory will be kept and can be included in the repository.

You can view additional help for setup.py by running

python setup.py --help

or

python setup.py --help-commands

condatests.py

Important

The following assumes that you are using conda as your environment manager.

Additionally, there is a condatests.py file that is created by running msl create. This script will run the tests in all specified conda environments. At the time of writing this script, tox and conda were not compatible and so this script provided a way around this issue.

You can either pass options from the command line or by creating a configuration file.

command line

condatests.py accepts the following command-line arguments:

  • --create - the Python version numbers to use to create conda environments (e.g., 2 3.6 3.7.2)

  • --include - the conda environments to include (supports regex)

  • --exclude - the conda environments to exclude (supports regex)

  • --requires - additional packages to install for the tests (can also be a path to a file)

  • --command - the command to execute with each conda environment

  • --ini - the path to a configuration file

  • --list - list the conda environments that will be used for the tests and then exit

You can view the help for condatests.py by running

python condatests.py --help

Run the tests with all conda environment's using the python -m pytest command. This assumes that a configuration file does not exist (which could change the default options).

python condatests.py

Run the tests with all conda environments that include py in the environment name

python condatests.py --include py

Run the tests with all conda environments but exclude those that contain py26 and py33 in the environment name

python condatests.py --exclude py26 py33

Tip

Since a regex search is used to filter the environment names that follow the --exclude (and also the --include) option, the above command could be replaced with --exclude "py(26|33)". Surrounding the regex pattern with a " is necessary so that the OR, |, regex symbol is not mistaken for a pipe symbol.

Run the tests with all conda environments that include dev in the environment name but exclude those with dev33 in the environment name

python condatests.py --include dev --exclude dev33

Create new conda environments for the specified Python versions (if the minor or micro version numbers are not specified then the latest Python version that is available to conda will be installed). After the test finishes the newly-created environment is removed. For example, the following command will create environments for the latest Python 2.x.x version, for the latest Python 3.6.x version and for Python 3.7.4 and exclude all environments that already exist

python condatests.py --create 2 3.6 3.7.4 --exclude .

You can also mix the --create, --include and --exclude arguments

python condatests.py --create 3.7 --include dev --exclude dev33

Run the tests with all conda environments using the command nosetests

python condatests.py --command nosetests

Run the tests with all conda environments using the command unittest discover -s tests/

python condatests.py --command "unittest discover -s tests/"

Run the tests with all conda environments using the command unittest discover -s tests/ and ensure that all the packages specified in a requirements file are installed in each environment

python condatests.py --command "unittest discover -s tests/" --requires my_requirements.txt

List all conda environments that will be used for the tests and then exit

python condatests.py --list

You can also use –show as an alias for –list

python condatests.py --show

List the conda environments that include dev in the environment name and then exit

python condatests.py --include dev --list

Specify the path to a condatests.ini file

python condatests.py --ini C:\Users\Me\my_condatests_config.ini

configuration file

In addition to passing command line options, you can also save the options in an condatests.ini configuration file. This is a standard ini-style configuration file with the options create, include, exclude, command and requires specified under the [envs] section.

If a condatests.ini configuration file exists in the current working directory then it will automatically be loaded by running

python condatests.py

Alternatively, you can also specify the path to the configuration file from the command line

python condatests.py --ini C:\Users\Me\my_condatests_config.ini

You can pass in command-line arguments as well as reading from the configuration file. The following will load the condatests.ini file in the current working directory, print the conda environments that will be used for the tests and then exit

python condatests.py --show

Since every developer can name their environments to be anything that they want, the condatests.ini file is included in .gitignore.

The following are example condatests.ini files.

Example 1: Run python -m pytest (see setup.py) with all conda environments except for the base environment

[envs]
exclude=base

Example 2: Run python -m pytest with all conda environments that include the text py in the name of the environment but exclude the environments that contain py33 in the name (recall that a regex search is used to filter the environment names)

[envs]
include=py
exclude=py33

Example 3: Run python -m pytest only with newly-created conda environments, exclude all environments that already exist and ensure that scipy is installed in each new environment (if the minor or micro version numbers of the Python environments are not specified then the latest Python version that is available to conda will be installed)

[envs]
create=2 3.5 3.6 3.7
exclude=.
requires=scipy

Example 4: Run python -m pytest with newly-created conda environments and all conda environments that already exist that contain the text dev in the name of the environment except for the dev33 environment

[envs]
create=3.6 3.7.3 3.7.4
include=dev
exclude=dev33

Example 5: Run unittest, for all modules in the tests directory, with all conda environments that include the text dev in the environment name

[envs]
include=dev
command=unittest discover -s tests/

Example 6: Run pytest with customized options (i.e., ignoring any pytest.ini, tox.ini or setup.cfg files that might exist) with the specified conda environments.

[envs]
create=3.7
include=dev27 myenvironment py36
command=pytest -c condatests.ini

[pytest]
addopts =
   -x
  --verbose

Note

The environment names specified in the create, include, exclude and requires option can be separated by a comma, by whitespace or both. So, include=py27,py36,py37, include=py27 py36 py37 and include=py27, py36, py37 are all equivalent.