User documentation

PyBuilder Pip Tools is a PyBuilder plugin which generates *requirements*.txt files from your project plugin/build/install dependencies and keeps your virtual env in sync with them. This is achieved with pip-compile and pip-sync from pip-tools. No distinction is made between plugin and build dependencies; plugin dependencies are treated as build dependencies.

The plugin adds the pip_sync task and 2 project properties: $pybuilder_pip_tools_urls and $pybuilder_pip_tools_build_urls. The properties allow specifying dependency urls for regular and build/plugin dependencies respectively:

project.build_depends_on('pybuilder', '>0.9.0')

Urls must have a fragment containing egg={pkg_name}-{version}. version is unused and can be set to 0, pkg_name must match one of the project’s (build) dependencies.

The pip_sync task first generates these requirements files (with pip-compile):

Requirements file generated by pip-compile using project.dependencies (including their version constraints; as specified by project.depends_on) as file.
Analog to requirements.txt, but override project.dependencies with their url in $pybuilder_pip_tools_urls, if any.
Analog to requirements.txt, using project.build_dependencies (project.build_depends_on) + project.plugin_dependencies instead.
Analog to requirements.txt, using project.build_dependencies, project.plugin_dependencies and $pybuilder_pip_tools_urls instead.

For example, for the snippet above this would generate:

  • build_requirements.txt:

    pybuilder==0.9.1  # some version >0.9.0
    # pybuilder dependencies, also pinned
  • build_requirements_development.txt:

      -e git+>0.9.0
      # pybuilder dependencies, pinned
    Note: ``pip-compile`` only supports ``-e`` urls, so ``-e`` is prepended.
  • requirements.txt: empty, no project.dependencies specified.

  • requirements_development.txt: empty, no project.dependencies specified.

Finally, pip_sync runs:

pip-sync requirements_development.txt build_requirements_development.txt

The non-development requirements files may come in handy for syncing on a test/build server (E.g. travis, GitLab) or for deployment (E.g. making a self-contained executable).