“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:
pytest.ini - used even if it does not contain a [pytest] section
tox.ini - must contain a [pytest] section to be used
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.