iter-together

Simultaneously iterate over multiple files with the same index column.

This package was written to accompany the tutorial Reusable, Reproducible, Useful Computational Science in Python that was organized by CoronaWhy and presented by Charles Tapley Hoyt on June 3rd, 2020. Recording available at https://youtu.be/lo_g-GbYtaA. I've written several blog posts covering the topics presented here in more detail at:

• https://cthoyt.com/2020/06/03/how-to-code-with-me-organization.html
• https://cthoyt.com/2020/06/11/click.html
• https://cthoyt.com/2020/04/25/how-to-code-with-me-flake8.html

Ignore the Junk

This repository uses a .gitignore file to make sure no junk gets committed. GitHub will ask you if you want a pre-populated .gitignore added to your repo on creation. You can also go to https://www.gitignore.io/ to get more options.

Things that are especially bad to commit to repos:

• compiled python files (*.pyc)
• Jupyter notebook checkpoint folders (.ipynb_checkpoints/)
• documentation builds (let ReadTheDocs take care of this!)
• tox and other automation/build tool caches
• basically any file you didn't make on purpose

License

The code in this repository is distributed under the MIT License. You should always add a license to your repository otherwise other people can't legally use it. If you're working alone, it's also best to license the repository under your name!

You can check https://choosealicense.com/ to understand the differences between open source software licenses.

Installation

iter-together can be installed in development mode with:

$ git clone https://travis-ci.com/cthoyt-teaches-reproducibility/iter-together-FINISHED.git iter-together
$ cd iter-together
$ pip install -e .[docs]

• -e installs in editable mode
• . says install the current directory
• [docs] says install the extra requirements for building the docs

It can also be installed in ready-to-go mode from the latest code on GitHub with:

$ pip install git+https://travis-ci.com/cthoyt-teaches-reproducibility/iter-together-FINISHED.git

Documentation

Documentation is automatically built with every push to master and served by ReadTheDocs at https://cthoyt-teaches-reproducibility-iter-together-finished.readthedocs.io.

If you want to build the documentation locally after cloning the repository and installing in development mode, you can do the following to build and open the docs (sorry windows users, you're out of luck):

$ cd docs/
$ make html
$ open build/html/index.html

Automated Testing

All of the settings for checking package metadata quality (pyroma), package integrity (MANIFEST.in, check-manifest), code quality (flake8), documentation quality (doc8), running unit tests (pytest), checking code coverage (codecov; coverage-report) can be run with tox with the following:

$ pip install tox
$ tox

Later, it automatically gets run by Travis-CI on every push.

Versioning

This project uses semantic versioning (https://semver.org/) that is handled by bumpversion. The configuration is in .bumpversion.cfg. If you want to bump the version, you can do the following:

$ pip install bumpversion
$ bumpversion patch

This makes the version go from X.Y.Z to X.Y.(Z+1)-dev. The same can be done for Y and Z with bumpversion minor and bumpversion major. To get rid of the -dev prefix (only do this just before releasing) you can use bumpversion release.

Note: you have to make sure you have a clean working directory before running this! That means no uncommitted files.

Releasing to PyPI

PyPI is pronounced Py-Pee-Eye! After doing bumpversion release, you should release to Test PyPI using the following:

pip install wheel twine
python setup.py -q sdist bdist_wheel
twine upload --skip-existing --repository-url https://test.pypi.org/simple/ dist/*

More information on twine can be found at https://packaging.python.org/guides/using-testpypi/#using-testpypi-with-pip. When you're doing this for real, you don't need --repository-url https://test.pypi.org/simple/.

Remembering the bumpversion and release commands is a pain, so there's a magical command in tox.ini called finish that can be run like with tox -e finish. It takes care of bumping the version to a release version, making the distributions, pushing to PyPI, pushing to git, bumping the version with the next patch, then pushing to git again.