Reqwire introduces a requirements base directory to the root of your project, and two subdirectories: a source directory and a build directory. By default, the source directory is named src, and the build directory is named lck (for lock, as built requirements.txt files are analogous to the lock files of many other package managers).
The names for all three of these directories are configurable, by
--build-directory options, respectively, to
any commands. For example:
$ reqwire -d req --source-directory=_src --build-directory=_build build -a
$ export REQWIRE_DIR_BASE=req
$ export REQWIRE_DIR_SOURCE=_src
$ export REQWIRE_DIR_BUILD=_build
$ reqwire build -a
Packaging and Version Control¶
Ideally, the requirements directory should be located in a project’s
root directory, and both source and build directories added to version
control. Depending on the project and target audience, it might make
sense to copy or symlink the primary, built requirements tag (usually
main) to a
requirements.txt file in the project root.
If you’re distributing a Python package, it might be useful to Include
the build directory in your MANIFEST.in file. This can be simply
Take care to ensure that the built requirements directory is not
.hgignore, etc. This should not be a
problem if using the default build directory name (lck).
The purpose of tags in reqwire is to provide logical separation of package requirements based on the environment they target. For instance, Sphinx is likely only needed when building documentation, and not at runtime. pytest and pytest plugins are only required in a continuous integration (CI) environment, and so on.
Traditionally, you would use tools like tox, and end up maintaining requirements in more than one location, and likely not bother to pin versions or declare sub-dependencies. reqwire makes it convenient for package maintainers to quickly generate concrete, first-level requirements, which should hopefully encourage best practices across all environments.
reqwire add [specifier]...
Installs packages to the local environment and updates one or more tagged requirement source files.
If no other parameters are given, this command will...
- Resolve the latest version of the provided package(s), unless a pinned version is provided.
- Install the package with pip.
- Add the requirement to the
reqwire add -b [specifier]...
Calls reqwire build for each tag provided (or
mainif no tags were provided).
reqwire add -e [path/url]
Adds an editable project.
reqwire add [-t <tag name>]... [specifier]...
Saves packages to the specified requirement tag(s).
reqwire add --no-install [specifier]...
Skips package installation.
reqwire add --no-resolve-canonical-names [specifier]...
By default, reqwire will search the Python package index for an exact match of package names, and use the canonical name (i.e. casing) for each specifier.
Passing this flag results in the user-provided package being saved to requirement source files.
reqwire add --no-resolve-versions [specifier]...
By default, reqwire will resolve the latest version for each specifier provided.
Passing this flag allows for adding non-pinned packages to requirement source files. In most cases, this is not recommended even though the resulting requirement lock files will resolve to latest versions anyway.
reqwire add --pre [specifier]...
Includes prerelease versions when resolving versions.
reqwire build -a
Builds all tags.
reqwire build -t TAG
Builds one or more tags.
reqwire build -a -- [pip-compile options]...
Passes all additional options and arguments to pip-compile.
For instance, to build requirements with hashes:
$ reqwire build -a -- --generate-hashes
Scaffolds a requirements directory in the current directory.
reqwire init -f
Scaffolds a requirements directory and overwrites any default tag names, and ignores pre-existing directories.
reqwire init --index-url=INDEX_URL
Changes the base URL written to requirement source files.
reqwire init -t TAG
Creates the given tag names as requirement source files.
If not provided, the tags
testwill get created.
reqwire init --extra-index-url INDEX_URL
extra-index-urloptions to requirement source files.
reqwire remove [specifier]...
Removes the provided package name(s) from the main requirement source file.
reqwire remove -t TAG [specifier]...
Removes the provided package name(s) from one or more tagged requirement source files.