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')
project.get_property('pybuilder_pip_tools_build_urls').extend([
      'git+https://github.com/pybuilder/pybuilder.git#egg=pybuilder-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.txt

Requirements file generated by pip-compile using project.dependencies (including their version constraints; as specified by project.depends_on) as requirements.in file.

requirements_development.txt

Analog to requirements.txt, but override project.dependencies with their url in $pybuilder_pip_tools_urls, if any.

build_requirements.txt

Analog to requirements.txt, using project.build_dependencies (project.build_depends_on) + project.plugin_dependencies instead.

build_requirements_development.txt

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+https://github.com/pybuilder/pybuilder.git#egg=pybuilder-0>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).