Documentation

[uranusjr]

Documentation

[uranusjr]

The current CLI design follows (loosely) Sam Boyer’s map-sync-memo proposal, but with naming tweaks (to match Pipenv).

There are conceptually four representations that need to be kept in sync. They are defined as

• p Project intent
• m Manifest (Pipfile)
• l Lock file (Pipfile.lock)
• d Dependency code (actually installed packages)

And the three sync operations are

• M(p,m) Modify the Pipfile to add/remove/modify package declarations.
• L(m,l) Execute the locker to generate a new Pipfile.lock.
• D(l,d) Synchronize the environment based on Pipfile.lock, installing needed, uninstalling superfluous.

Mapping them to commands in Passa:

• add is M∘L∘D; add --no-sync is M∘L.
• clean is a partial D.
• freeze is not related to this process.
• install is L∘D with a special hash check.
• lock is L.
• remove is M∘L∘D (D is partial; only cleaning); remove --no-clean is M∘L.
• sync is S.
• upgrade is L∘D; upgrade --no-sync is M∘L.

Note that the meanings of install and sync are flipped to match Pipenv.

Compared to Boyer’s method, D(l,d) is actually split into two parts in Passa. sync can be logically separated into sync --no-clean and clean. remove only does D halfway, and both add and upgrade also have a switch to achieve this halfway state. This special feature is designed to fit a common Python app development use case, allowing the user to keep stray, untracked packages in the virtual environment.