Conda kapsels are reproducible, executable project directories.
Take any directory full of stuff that you're working on; web apps, scripts, Jupyter notebooks, data files, whatever it may be.
By adding a
kapsel.yml to this project directory, you can tell
conda how to run it.
Running a conda kapsel executes a command specified in the
kapsel.yml (any arbitrary commands can be configured).
kapsel.yml also tells conda how to automate project setup; conda
can establish all prerequisite conditions for the project's
commands to execute successfully. These conditions could include:
- creating a conda environment with certain packages in it
- prompting the user for passwords or other configuration
- downloading data files
- starting extra processes such as a database server
The goal is that if your project runs on your machine, it will also run on others' machines (or on your future machine after you reboot a few times and forget how your project works).
conda kapsel init DIRECTORY_NAME creates a
kapsel.yml, converting your project directory into a conda
Put another way...
Traditional build scripts such as
setup.py automate "building"
the project (going from source code to something runnable), while
conda kapsel automates "running" the project (taking build
artifacts and doing any necessary setup prior to executing them).
- Do you have a README with setup steps in it? You may find that
it gets outdated, or that people don't read it, and then you
have to help them diagnose the problem.
conda kapselautomates the setup steps; the README can say "type
conda kapsel run" and that's it.
- Do you need everyone working on a project to have the same
dependencies in their conda environment?
conda kapselautomates environment creation and verifies that environments have the right versions of packages.
- Do you sometimes include your personal passwords or secret keys
in your code, because it's too complicated to do otherwise?
conda kapsel, you can
conda kapselto prompt the user for any missing credentials.
- Do you want improved reproducibility? With
conda kapsel, someone who wants to reproduce your analysis can ensure they have exactly the same setup that you have on your machine.
- Do you want to deploy your analysis as a web application? The
kapsel.ymltells hosting providers how to run your project, so there's no special setup needed when you move from your local machine to the web.
See http://conda.pydata.org/docs/kapsel/ for a simple getting-started walkthrough.
See http://conda.pydata.org/docs/kapsel/config.html for more detail on
the syntax of the
If you've been using
conda env and
conda kapsel has similar functionality and may be more
convenient. The advantage of
conda kapsel for environment
handling is that it performs conda operations, and records them
in a config file for reproducibility, in one step.
For example, if you do
conda kapsel add-packages bokeh=0.11,
that will install Bokeh with conda, and add
bokeh=0.11 to an
environment spec in
kapsel.yml (the effect is comparable to
adding it to
environment.yml). In this way, "your current conda
environment's state" and "your configuration to be shared with
others" won't get out of sync.
conda kapsel will also automatically set up environments for a
colleague when they type
conda kapsel run on their machine; they
don't have to do a separate step to create, update, or activate
environments before they run the code. This may be especially
useful when you change the required dependencies; with
people can forget to re-run it and update their packages, while
conda kapsel run will automatically add missing packages every
In addition to environment creation,
conda kapsel can perform
other kinds of setup, such as adding data files and running a
database server. It's a superset of
conda env in that sense.
For the time being, the conda kapsel API and command line syntax are subject to change in future releases. A project created with the current “beta” version of conda kapsel may always need to be run with that version of conda kapsel and not conda kapsel 1.0. When we think things are solid, we’ll switch from “beta” to “1.0” and you’ll be able to rely on long-term interface stability.
Please report issues right here on GitHub.
Please join our chat room at https://gitter.im/conda/kapsel if you have questions, feedback, or just want to say hi.
Here's how to work on the code:
python setup.py testis configured to run all the checks that have to pass before you commit or push. It also reformats the code with yapf if necessary. Continuous integration runs this command so you should run it and make it pass before you push to the repo.
- To only run the formatter and linter, use
python setup.py test --format-only.
- To only run the tests, use
python -m pytest -vv conda_kapsel
- To only run a single file of tests use
python -m pytest -vv conda_kapsel/test/test_foo.py
- To only run a single test function
python -m pytest -vv conda_kapsel/test/test_foo.py::test_something
- There's a script
build_and_upload.shthat should be used to manually make a release. The checked-out revision should have a version tag prior to running the script.