New env command and sub commands (#731)

* Add a env:info command * Add env:use command * Fix tests on Windows * Fix tests * Fix tests * Fix tests for Python 3.5 * Use a hash in virtualenv names dependent on the project’s path * Add tests for the `env use` command * Fix tests * Add a `env list` command * Fix venvs being recreated when switching minor Python versions * Add a `env remove` command * Update CHANGELOG * Update documentation
python-poetry · Dec 18, 2018 · 3c26c8d · 3c26c8d
1 parent 41c2736
commit 3c26c8d
Show file tree

Hide file tree

Showing 32 changed files with 1,606 additions and 167 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,10 @@
 ### Added
 
 - Added an `export` command to export the lock file to other formats (only `requirements.txt` is currently supported).
+- Added a `env info` command to get basic information about the current environment.
+- Added a `env use` command to control the Python version used by the project.
+- Added a `env list` command to list the virtualenvs associated with the current project.
+- Added a `env remove` command to delete virtualenvs associated with the current project.
 
 ### Changed
 
@@ -13,6 +17,7 @@
 - The `debug:info` command has been renamed to `debug info`.
 - The `debug:resolve` command has been renamed to `debug resolve`.
 - The `self:update` command has been renamed to `self update`.
+- Changed the way virtualenvs are stored (names now depend on the project's path).
 
 ### Fixed
 

diff --git a/docs/docs/basic-usage.md b/docs/docs/basic-usage.md
@@ -155,19 +155,99 @@ When you execute the `install` command (or any other "install" commands like `ad
 Poetry will check if it's currently inside a virtualenv and, if not, will use an existing one
 or create a brand new one for you to always work isolated from your global Python installation.
 
-!!!note
+By default, Poetry will use the currently activated Python version
+to create the virtualenv for the current project.
+
+To easily switch between Python versions, it is recommended to
+use [pyenv](https://github.com/pyenv/pyenv) or similar tools.
+
+For instance, if your project is Python 2.7 only, a standard workflow
+would be:
+
+```bash
+pyenv install 2.7.15
+pyenv local 2.7.15  # Activate Python 2.7 for the current project
+poetry install
+```
+
+However, this might not be feasible for your system, especially Windows where `pyenv`,
+is not available. To circumvent that you can use the `env use` command to tell
+Poetry which Python version to use for the current project.
 
-    To create the virtualenv for the current project, Poetry will use
-    the currently activated Python version.
+```bash
+poetry env use /full/path/to/python
+```
+
+If you have the python executable in your `PATH` you can use it:
+
+```bash
+poetry env use python3.7
+```
 
-    To easily switch between Python versions, it is recommended to
-    use [pyenv](https://github.com/pyenv/pyenv) or similar tools.
+You can even just use the minor Python version in this case:
 
-    For instance, if your project is Python 2.7 only, a standard workflow
-    would be:
+```bash
+poetry env use 3.7
+```
+
+If you want to disable the explicitly activated virtualenv, you can use the
+special `system` Python version to retrieve the default behavior:
+
+```bash
+poetry env use system
+```
+
+If you want to get basic information about the currently activated virtualenv,
+you can use the `env info` command:
+
+```bash
+poetry env info
+```
+
+will output something similar to this:
+
+```text
+Virtualenv
+Python:         3.7.1
+Implementation: CPython
+Path:           /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7
+Valid:          True
+
+System
+Platform: darwin
+OS:       posix
+Python:   /path/to/main/python
+```
+
+If you only want to know the path to the virtualenv, you can pass the `--path` option
+to `env info`:
+
+```bash
+poetry env info --path
+```
+
+You can also list all the virtualenvs associated with the current virtualenv
+with the `env list` command:
+
+```bash
+poetry env list
+```
+
+will output something like the following:
+
+```text
+test-O3eWbxRl-py2.7
+test-O3eWbxRl-py3.6
+test-O3eWbxRl-py3.7 (Activated)
+```
+
+Finally, you can delete existing virtualenvs by using `env remove`:
+
+```bash
+poetry env remove /full/path/to/python
+poetry env remove python3.7
+poetry env remove 3.7
+poetry env remove test-O3eWbxRl-py3.7
+```
 
-    ```bash
-    pyenv install 2.7.15
-    pyenv local 2.7.15  # Activate Python 2.7 for the current project
-    poetry install
-    ```
+If your remove the currently activated virtualenv, it will be automatically deactivated.
diff --git a/docs/docs/cli.md b/docs/docs/cli.md
@@ -375,3 +375,112 @@ poetry export -f requirements.txt
 !!!note
 
     Only the `requirements.txt` format is currently supported.
+
+## env
+
+The `env` command regroups sub commands to interact with the virtualenvs
+associated with a specific project.
+
+### env use
+
+The `env use` command tells Poetry which Python version
+to use for the current project.
+
+```bash
+poetry env use /full/path/to/python
+```
+
+If you have the python executable in your `PATH` you can use it:
+
+```bash
+poetry env use python3.7
+```
+
+You can even just use the minor Python version in this case:
+
+```bash
+poetry env use 3.7
+```
+
+If you want to disable the explicitly activated virtualenv, you can use the
+special `system` Python version to retrieve the default behavior:
+
+```bash
+poetry env use system
+```
+
+### env info
+
+The `env info` command displays basic information about the currently activated virtualenv:
+
+```bash
+poetry env info
+```
+
+will output something similar to this:
+
+```text
+Virtualenv
+Python:         3.7.1
+Implementation: CPython
+Path:           /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7
+Valid:          True
+
+System
+Platform: darwin
+OS:       posix
+Python:   /path/to/main/python
+```
+
+If you only want to know the path to the virtualenv, you can pass the `--path` option
+to `env info`:
+
+```bash
+poetry env info --path
+```
+
+#### Options
+
+* `--path`: Only display the path of the virtualenv.
+
+
+### env list
+
+The `env list` command lists all the virtualenvs associated with the current virtualenv.
+
+```bash
+poetry env list
+```
+
+will output something like the following:
+
+```text
+test-O3eWbxRl-py2.7
+test-O3eWbxRl-py3.6
+test-O3eWbxRl-py3.7 (Activated)
+```
+
+#### Options
+
+* `--full-path`: Display the full path of the virtualenvs.
+
+### env remove
+
+The `env remove` command deletes virtualenvs associated with the current project:
+
+```bash
+poetry env remove /full/path/to/python
+```
+
+Similarly to `env use`, you can either pass `python3.7`, `3.7` or the name of
+the virtualenv (as returned by `env list`):
+
+```bash
+poetry env remove python3.7
+poetry env remove 3.7
+poetry env remove test-O3eWbxRl-py3.7
+```
+
+!!!note
+
+    If your remove the currently activated virtualenv, it will be automatically deactivated.
diff --git a/poetry/console/application.py b/poetry/console/application.py
@@ -33,6 +33,8 @@
 
 from .config import ApplicationConfig
 
+from .commands.env import EnvCommand
+
 
 class Application(BaseApplication):
     def __init__(self):
@@ -89,6 +91,9 @@ def get_default_commands(self):  # type: () -> list
         # Debug command
         commands += [DebugCommand()]
 
+        # Env command
+        commands += [EnvCommand()]
+
         # Self commands
         commands += [SelfCommand()]
 

diff --git a/poetry/console/commands/debug/info.py b/poetry/console/commands/debug/info.py
@@ -1,6 +1,8 @@
 import os
 import sys
 
+from clikit.args import StringArgs
+
 from ..command import Command
 
 
@@ -12,54 +14,21 @@ class DebugInfoCommand(Command):
     """
 
     def handle(self):
-        from ....utils.env import Env
-
-        poetry = self.poetry
-        env = Env.get(poetry.file.parent)
-
         poetry_python_version = ".".join(str(s) for s in sys.version_info[:3])
 
         self.line("")
         self.line("<b>Poetry</b>")
-        self.line("")
-        self.line("<info>Version</info>: <comment>{}</>".format(poetry.VERSION))
-        self.line("<info>Python</info>:  <comment>{}</>".format(poetry_python_version))
-
-        self.line("")
-
-        env_python_version = ".".join(str(s) for s in env.version_info[:3])
-        self.line("<b>Virtualenv</b>")
-        self.line("")
-        listing = [
-            "<info>Python</info>:         <comment>{}</>".format(env_python_version),
-            "<info>Implementation</info>: <comment>{}</>".format(
-                env.python_implementation
-            ),
-            "<info>Path</info>:           <comment>{}</>".format(
-                env.path if env.is_venv() else "NA"
-            ),
-        ]
-        if env.is_venv():
-            listing.append(
-                "<info>Valid</info>:          <{tag}>{is_valid}</{tag}>".format(
-                    tag="comment" if env.is_sane() else "error", is_valid=env.is_sane()
-                )
+        self.line(
+            "\n".join(
+                [
+                    "<info>Version</info>: <comment>{}</>".format(self.poetry.VERSION),
+                    "<info>Python</info>:  <comment>{}</>".format(
+                        poetry_python_version
+                    ),
+                ]
             )
+        )
+        args = StringArgs("")
+        command = self.application.get_command("env").get_sub_command("info")
 
-        for line in listing:
-            self.line(line)
-
-        self.line("")
-
-        self.line("<b>System</b>")
-        self.line("")
-        listing = [
-            "<info>Platform</info>: <comment>{}</>".format(sys.platform),
-            "<info>OS</info>:       <comment>{}</>".format(os.name),
-            "<info>Python</info>:   <comment>{}</>".format(env.base),
-        ]
-
-        for line in listing:
-            self.line(line)
-
-        self.line("")
+        return command.run(args, self._io)
diff --git a/poetry/console/commands/debug/resolve.py b/poetry/console/commands/debug/resolve.py
@@ -24,7 +24,7 @@ def handle(self):
         from poetry.puzzle import Solver
         from poetry.repositories.repository import Repository
         from poetry.semver import parse_constraint
-        from poetry.utils.env import Env
+        from poetry.utils.env import EnvManager
 
         packages = self.argument("package")
 
@@ -78,7 +78,7 @@ def handle(self):
 
             return 0
 
-        env = Env.get(self.poetry.file.parent)
+        env = EnvManager(self.poetry.config).get(self.poetry.file.parent)
         current_python_version = parse_constraint(
             ".".join(str(v) for v in env.version_info)
         )

diff --git a/poetry/console/commands/env/__init__.py b/poetry/console/commands/env/__init__.py
@@ -0,0 +1 @@
+from .env import EnvCommand
diff --git a/poetry/console/commands/env/env.py b/poetry/console/commands/env/env.py
@@ -0,0 +1,19 @@
+from ..command import Command
+
+from .info import EnvInfoCommand
+from .list import EnvListCommand
+from .remove import EnvRemoveCommand
+from .use import EnvUseCommand
+
+
+class EnvCommand(Command):
+    """
+    Interact with Poetry's project environments.
+
+    env
+    """
+
+    commands = [EnvInfoCommand(), EnvListCommand(), EnvRemoveCommand(), EnvUseCommand()]
+
+    def handle(self):  # type: () -> int
+        return self.call("help", self._config.name)