Merge pull request #5366 from pypa/named-categories

Support Named Package Categories

Pipfile

@@ -1,3 +1,8 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
 [dev-packages]
 pipenv = {path = ".", editable = true, extras = ["tests", "dev"]}
 sphinx = "==4.*"

docs/basics.rst

@@ -283,6 +283,32 @@ the current working directory when working on packages::
           ``Pipfile.lock`` if you leave the ``-e`` option out.
 
 
+☤ Specifying Package Categories
+-------------------------------
+
+Originally pipenv supported only two package groups:  ``packages`` and ``dev-packages`` in the ``Pipfile`` which mapped to ``default`` and ``develop`` in the ``Pipfile.lock``.   Support for additional named categories has been added such that arbitrary named groups can utilized across the available pipenv commands.
+
+.. note:: The name will be the same between ``Pipfile`` and lock file, however to support the legacy naming convention it is not possible to have an additional group named ``default`` or ``develop`` in the ``Pipfile``.
+
+By default ``pipenv lock`` will lock all known package categorises; to specify locking only specific groups use the ``--categories`` argument.
+The command should process the package groups in the order specified.
+
+Example usages::
+
+	# single category
+	pipenv install six --catetgories prereq
+
+	# multiple categories
+	pipenv sync --categories="prereq packages"
+
+	# lock and uninstall examples
+	pipenv lock --categories="prereq dev-packages"
+	pipenv uninstall six --categories prereq
+
+
+
+.. note:: The ``packages``/``default`` specifiers are used to constrain all other categories just as they have done for ``dev-packages``/``develop`` category.  However this is the only way constraints are applied -- the presence of other named groups do not constraint each other, which means it is possible to define conflicting package versions across groups.  This may be desired in some use cases where users only are installing groups specific to their system platform.
+
 .. _environment_management:
 
 ☤ Environment Management with Pipenv

pipenv/cli/command.py

@@ -240,7 +240,6 @@ def install(state, **kwargs):
         python=state.python,
         pypi_mirror=state.pypi_mirror,
         system=state.system,
-        lock=not state.installstate.skip_lock,
         ignore_pipfile=state.installstate.ignore_pipfile,
         skip_lock=state.installstate.skip_lock,
         requirementstxt=state.installstate.requirementstxt,
@@ -253,6 +252,7 @@ def install(state, **kwargs):
         editable_packages=state.installstate.editables,
         site_packages=state.site_packages,
         extra_pip_args=state.installstate.extra_pip_args,
+        categories=state.installstate.categories,
     )
 
 
@@ -291,6 +291,7 @@ def uninstall(ctx, state, all_dev=False, all=False, **kwargs):
         all=all,
         keep_outdated=state.installstate.keep_outdated,
         pypi_mirror=state.pypi_mirror,
+        categories=state.installstate.categories,
         ctx=ctx,
     )
     if retcode:
@@ -341,6 +342,7 @@ def lock(ctx, state, **kwargs):
         keep_outdated=state.installstate.keep_outdated,
         pypi_mirror=state.pypi_mirror,
         write=not state.quiet,
+        categories=state.installstate.categories,
     )
 
 
@@ -654,6 +656,7 @@ def sync(ctx, state, bare=False, user=False, unused=False, **kwargs):
         pypi_mirror=state.pypi_mirror,
         system=state.system,
         extra_pip_args=state.installstate.extra_pip_args,
+        categories=state.installstate.categories,
     )
     if retcode:
         ctx.abort()

pipenv/cli/options.py

@@ -88,6 +88,7 @@ def __init__(self):
         self.packages = []
         self.editables = []
         self.extra_pip_args = []
+        self.categories = []
 
 
 class LockOptions:
@@ -223,6 +224,24 @@ def callback(ctx, param, value):
     )(f)
 
 
+def categories_option(f):
+    def callback(ctx, param, value):
+        state = ctx.ensure_object(State)
+        if value:
+            for opt in value.split(" "):
+                state.installstate.categories.append(opt)
+        return value
+
+    return option(
+        "--categories",
+        nargs=1,
+        required=False,
+        callback=callback,
+        expose_value=True,
+        type=click_types.STRING,
+    )(f)
+
+
 def install_dev_option(f):
     return _dev_option(f, "Install both develop and default packages")
 
@@ -547,6 +566,7 @@ def install_base_options(f):
 
 def uninstall_options(f):
     f = install_base_options(f)
+    f = categories_option(f)
     f = uninstall_dev_option(f)
     f = skip_lock_option(f)
     f = editable_option(f)
@@ -558,12 +578,14 @@ def lock_options(f):
     f = install_base_options(f)
     f = lock_dev_option(f)
     f = dev_only_flag(f)
+    f = categories_option(f)
     return f
 
 
 def sync_options(f):
     f = install_base_options(f)
     f = install_dev_option(f)
+    f = categories_option(f)
     return f