From 4fb6cc3631d3c33e25e4ca291de5b394bc1fbd9d Mon Sep 17 00:00:00 2001 From: Tzu-ping Chung Date: Thu, 5 Jul 2018 14:39:41 +0800 Subject: [PATCH 1/4] Installation documentation updates Removed ppa mentions from documentation, and re-organised the page a bit to make it structurally easier to upderstand. Both the documentation's front page and README.rst now actively refer to the page so user can be directed to better installation methods. (I don't think this is very useful TBT because people don't use manuals, but we should still do it.) Also fixed many Sphinx warnings during documentation builds. --- README.md | 11 +-- docs/conf.py | 4 -- docs/dev/philosophy.rst | 4 +- docs/diagnose.rst | 2 +- docs/index.rst | 24 ++++--- docs/install.rst | 150 +++++++++++++++++----------------------- 6 files changed, 83 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index 0b224e16..c674d80c 100644 --- a/README.md +++ b/README.md @@ -44,20 +44,11 @@ If you\'re on MacOS, you can install Pipenv easily with Homebrew: $ brew install pipenv -If you\'re using Ubuntu 17.10: - - $ sudo apt install software-properties-common python-software-properties - $ sudo add-apt-repository ppa:pypa/ppa - $ sudo apt update - $ sudo apt install pipenv - Or, if you\'re using Fedora 28: $ sudo dnf install pipenv -Otherwise, just use pip: - - $ pip install pipenv +Otherwise, refer to the [documentation](https://docs.pipenv.org/install/) for instructions. ✨🍰✨ diff --git a/docs/conf.py b/docs/conf.py index d3e5c222..f3d0b6e2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,6 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os -import sys # Path hackery to get current version number. here = os.path.abspath(os.path.dirname(__file__)) @@ -182,7 +181,6 @@ texinfo_documents = [ ] - # -- Options for Epub output ---------------------------------------------- # Bibliographic Dublin Core info. @@ -202,5 +200,3 @@ epub_copyright = copyright # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] - - diff --git a/docs/dev/philosophy.rst b/docs/dev/philosophy.rst index bf7146a4..9d364e84 100644 --- a/docs/dev/philosophy.rst +++ b/docs/dev/philosophy.rst @@ -7,9 +7,9 @@ Pipenv is an open but opinionated tool, created by an open but opinionated devel Management Style ~~~~~~~~~~~~~~~~ -`Kenneth Reitz `_ is the BDFL. He has final say in any decision related to the Pipenv project. Kenneth is responsible for the direction and form of the library, as well as its presentation. In addition to making decisions based on technical merit, he is responsible for making decisions based on the development philosophy of Pipenv. +`Kenneth Reitz `__ is the BDFL. He has final say in any decision related to the Pipenv project. Kenneth is responsible for the direction and form of the library, as well as its presentation. In addition to making decisions based on technical merit, he is responsible for making decisions based on the development philosophy of Pipenv. -`Dan Ryan`_, `Tzu-ping Chung`_, and `Nate Prewitt`_ are the core contributors. +`Dan Ryan `__, `Tzu-ping Chung `__, and `Nate Prewitt `__ are the core contributors. They are responsible for triaging bug reports, reviewing pull requests and ensuring that Kenneth is kept up to speed with developments around the library. The day-to-day managing of the project is done by the core contributors. They are responsible for making judgements about whether or not a feature request is likely to be accepted by Kenneth. diff --git a/docs/diagnose.rst b/docs/diagnose.rst index 650e70a1..5cc47f4c 100644 --- a/docs/diagnose.rst +++ b/docs/diagnose.rst @@ -45,7 +45,7 @@ in your Pipfile. This is usually a result of mixing Pipenv with system packages. We *strongly* recommend installing Pipenv in an isolated environment. Uninstall all existing -Pipenv installations, and see :ref:`proper_installation` to choose one of the +Pipenv installations, and see :ref:`installing-pipenv` to choose one of the recommended way to install Pipenv instead. ☤ My pyenv-installed Python is not found diff --git a/docs/index.rst b/docs/index.rst index 840ae6ff..957d6c8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,20 +43,15 @@ The problems that Pipenv seeks to solve are multi-faceted: Install Pipenv Today! --------------------- -Just use pip:: +If you're on MacOS, you can install Pipenv easily with Homebrew:: - $ pip install pipenv + $ brew install pipenv -Or, if you're using Ubuntu 17.10:: +Or, if you're using Fedora 28:: - $ sudo apt install software-properties-common python-software-properties - $ sudo add-apt-repository ppa:pypa/ppa - $ sudo apt update - $ sudo apt install pipenv + $ sudo dnf install pipenv -Otherwise, if you're on MacOS, you can install Pipenv easily with Homebrew:: - - $ brew install pipenv +Otherwise, refer to the :ref:`installing-pipenv` chapter for instructions. ✨🍰✨ @@ -122,6 +117,15 @@ Further Documentation Guides advanced diagnose +Contribution Guides +------------------- + +.. toctree:: + :maxdepth: 2 + + dev/philosophy + dev/contributing + ☤ Pipenv Usage -------------- diff --git a/docs/install.rst b/docs/install.rst index 4766030d..9df6a5fc 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,5 +1,6 @@ .. _virtualenvironments-ref: +============================= Pipenv & Virtual Environments ============================= @@ -19,13 +20,11 @@ managing development and testing environments for any kind of project. should work fine on Python 2.7—if you are still using it, for some reason. -☤ Make sure you've got Python & pip ------------------------------------- +☤ Make sure you've got Python & pip +=================================== Before you go any further, make sure you have Python and that it's available -from your command line. You can check this by simply running: - -.. code-block:: bash +from your command line. You can check this by simply running:: $ python --version @@ -35,7 +34,7 @@ install the latest 3.x version from `python.org`_ or refer to the .. Note:: If you're newcomer and you get an error like this: - .. code-block:: python + .. code-block:: pycon >>> python Traceback (most recent call last): @@ -47,10 +46,8 @@ install the latest 3.x version from `python.org`_ or refer to the `getting started tutorial`_ for an introduction to using your operating system's shell and interacting with Python. -Additionally, you'll need to make sure you have :ref:`pip` available. You can -check this by running: - -.. code-block:: bash +Additionally, you'll need to make sure you have pip available. You can +check this by running:: $ pip --version pip 9.0.1 @@ -59,7 +56,7 @@ If you installed Python from source, with an installer from `python.org`_, or via `Homebrew`_ you should already have pip. If you're on Linux and installed using your OS package manager, you may have to `install pip `_ separately. -If you plan to install pipenv using Homebrew you can skip this step. The +If you plan to install Pipenv using Homebrew you can skip this step. The Homebrew installer takes care of pip for you. .. _getting started tutorial: https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly @@ -68,23 +65,48 @@ Homebrew installer takes care of pip for you. .. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/ -☤ Installing Pipenv -------------------- +.. _installing-pipenv: -:ref:`Pipenv` is a dependency manager for Python projects. If you're familiar +☤ Installing Pipenv +=================== + +Pipenv is a dependency manager for Python projects. If you're familiar with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those -tools. While :ref:`pip` can install Python packages, Pipenv is recommended as +tools. While pip can install Python packages, Pipenv is recommended as it's a higher-level tool that simplifies dependency management for common use cases. -Use ``pip`` to install Pipenv: +.. _npm: https://www.npmjs.com/ +.. _bundler: http://bundler.io/ -.. code-block:: python + +☤ Homebrew Installation of Pipenv +--------------------------------- + +Homebrew is a popular open-source package management system for macOS. + +Installing pipenv via Homebrew will keep pipenv and all of its dependencies in +an isolated virtual environment so it doesn't interfere with the rest of your +Python installation. + +Once you have installed `Homebrew`_ simply run:: + + $ brew install pipenv + +To upgrade pipenv at any time:: + + $ brew upgrade pipenv + + +☤ Pragmatic Installation of Pipenv +---------------------------------- + +If you have a working installation of pip, and maintain certain "toolchain" type Python modules as global utilities in your user environment, pip `user installs `_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software. + +To install:: $ pip install --user pipenv - - .. Note:: This does a `user installation`_ to prevent breaking any system-wide packages. If ``pipenv`` isn't available in your shell after installation, you'll need to add the `user base`_'s binary directory to your ``PATH``. @@ -105,32 +127,43 @@ Use ``pip`` to install Pipenv: user ``PATH`` permanently in the `Control Panel`_. You may need to log out for the ``PATH`` changes to take effect. -.. _npm: https://www.npmjs.com/ -.. _bundler: http://bundler.io/ + For more information, see the `user installs documentation `_. + + .. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE .. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs .. _modifying ~/.profile: https://stackoverflow.com/a/14638025 .. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx + +To upgrade pipenv at any time:: + + $ pip install --user --upgrade pipenv + + +☤ Crude Installation of Pipenv +------------------------------ + +If you don't even have pip installed, you can use this crude installation method, which will bootstrap your whole system:: + + $ curl https://raw.githubusercontent.com/kennethreitz/pipenv/master/get-pipenv.py | python + + ☤ Installing packages for your project --------------------------------------- +====================================== Pipenv manages dependencies on a per-project basis. To install packages, change into your project's directory (or just an empty directory for this -tutorial) and run: - -.. code-block:: bash +tutorial) and run:: $ cd myproject $ pipenv install requests Pipenv will install the excellent `Requests`_ library and create a ``Pipfile`` -for you in your project's directory. The :ref:`Pipfile` is used to track which +for you in your project's directory. The ``Pipfile`` is used to track which dependencies your project needs in case you need to re-install them, such as when you share your project with others. You should get output similar to this -(although the exact paths shown will vary): - -.. code-block:: text +(although the exact paths shown will vary):: Creating a Pipfile for this project... Creating a virtualenv for this project... @@ -161,7 +194,7 @@ when you share your project with others. You should get output similar to this ☤ Using installed packages --------------------------- +========================== Now that Requests is installed you can create a simple ``main.py`` file to use it: @@ -174,9 +207,7 @@ use it: print('Your IP is {0}'.format(response.json()['origin'])) -Then you can run this script using ``pipenv run``: - -.. code-block:: bash +Then you can run this script using ``pipenv run``:: $ pipenv run python main.py @@ -192,57 +223,6 @@ have access to your installed packages with ``$ pipenv shell``. ☤ Next steps ------------- +============ Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨ - -.. _proper_installation: - - -☤ Homebrew Installation of Pipenv -================================= - -Homebrew is a popular open-source package management system for macOS. - -Installing pipenv via Homebrew will keep pipenv and all of its dependencies in -an isolated virtual environment so it doesn't interfere with the rest of your -Python installation. - -Once you have installed `Homebrew `_ simply run:: - - $ brew install pipenv - -To upgrade pipenv at any time:: - - $ brew upgrade pipenv - -.. _pragmatic_installation: - -☤ Pragmatic Installation of Pipenv -================================== - -If you have a working installation of pip, and maintain certain "toolchain" type Python modules as global utilities in your user environment, pip `user installs `_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software. - -To install:: - - $ pip install --user pipenv - -For more information see the `user installs documentation `_, but to add the installed cli tools from a pip user install to your path, add the output of:: - - $ python -c "import site; import os; print(os.path.join(site.USER_BASE, 'bin'))" - -To upgrade pipenv at any time:: - - $ pip install --user --upgrade pipenv - -.. _crude_installation: - -☤ Crude Installation of Pipenv -============================== - -If you don't even have pip installed, you can use this crude installation method, which will bootstrap your whole system:: - - $ curl https://raw.githubusercontent.com/kennethreitz/pipenv/master/get-pipenv.py | python - -Congratulations, you now have pip and Pipenv installed! - From 9315887101ff905a98a803a81f5ea44cf1941818 Mon Sep 17 00:00:00 2001 From: Tzu-ping Chung Date: Wed, 11 Jul 2018 17:17:08 +0800 Subject: [PATCH 2/4] Only quote arguments during cmdify if needed --- pipenv/cmdparse.py | 9 ++++++++- tests/unit/test_cmdparse.py | 6 +++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/pipenv/cmdparse.py b/pipenv/cmdparse.py index aa3442b8..087a95b1 100644 --- a/pipenv/cmdparse.py +++ b/pipenv/cmdparse.py @@ -55,11 +55,18 @@ class Script(object): The result is then quoted into a pair of double quotes to be grouped. + An argument is intentionally not quoted if it does not contain + whitespaces. This is done to be compatible with Windows built-in + commands that don't work well with quotes, e.g. everything with `echo`, + and DOS-style (forward slash) switches. + The intended use of this function is to pre-process an argument list before passing it into ``subprocess.Popen(..., shell=True)``. See also: https://docs.python.org/3/library/subprocess.html#converting-argument-sequence """ return " ".join( - '"{0}"'.format(re.sub(r'(\\*)"', r'\1\1\\"', arg)) for arg in self._parts + arg if not next(re.finditer(r'\s', arg), None) + else '"{0}"'.format(re.sub(r'(\\*)"', r'\1\1\\"', arg)) + for arg in self._parts ) diff --git a/tests/unit/test_cmdparse.py b/tests/unit/test_cmdparse.py index 064eda79..06012d07 100644 --- a/tests/unit/test_cmdparse.py +++ b/tests/unit/test_cmdparse.py @@ -30,9 +30,9 @@ def test_extend(): @pytest.mark.run @pytest.mark.script def test_cmdify(): - script = Script('python', ['-c', "print('hello')"]) + script = Script('python', ['-c', "print('hello world')"]) cmd = script.cmdify() - assert cmd == '"python" "-c" "print(\'hello\')"', script + assert cmd == 'python -c "print(\'hello world\')"', script @pytest.mark.run @@ -44,6 +44,6 @@ def test_cmdify_complex(): ])) assert script.cmdify() == ' '.join([ '"C:\\Program Files\\Python36\\python.exe"', - '"-c"', + '-c', """ "print(\'Double quote: \\\"\')" """.strip(), ]), script From 86965203bffd6e4593bb17cca4b533309f90de0c Mon Sep 17 00:00:00 2001 From: Tzu-ping Chung Date: Wed, 11 Jul 2018 17:26:18 +0800 Subject: [PATCH 3/4] Add news fragment --- news/2563.bugfix | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 news/2563.bugfix diff --git a/news/2563.bugfix b/news/2563.bugfix new file mode 100644 index 00000000..4d2e6570 --- /dev/null +++ b/news/2563.bugfix @@ -0,0 +1,2 @@ +Improve quoting logic for ``pipenv run`` so it works better with Windows +built-in commands. From 24f90a4ac297c429e67f984692f0a5a45dc6af37 Mon Sep 17 00:00:00 2001 From: Tzu-ping Chung Date: Thu, 12 Jul 2018 00:56:21 +0800 Subject: [PATCH 4/4] Please report against the latest version --- .github/ISSUE_TEMPLATE.md | 2 +- .github/ISSUE_TEMPLATE/Bug_report.md | 2 +- .github/ISSUE_TEMPLATE/Feature_request.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 69e5dad2..e1530fcc 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,4 +1,4 @@ -Be sure to check the existing issues (both open and closed!). +Be sure to check the existing issues (both open and closed!), and make sure you are running the latest version of Pipenv. If you're requesting a new feature or leaving feedback, please use this forum instead: diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index 229919b8..0a9b3421 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -3,7 +3,7 @@ name: Bug report about: Create a report to help us improve --- -Be sure to check the existing issues (both open and closed!). +Be sure to check the existing issues (both open and closed!), and make sure you are running the latest version of Pipenv. If you're requesting a new feature or leaving feedback, please use this forum instead: diff --git a/.github/ISSUE_TEMPLATE/Feature_request.md b/.github/ISSUE_TEMPLATE/Feature_request.md index 5418f88e..4292912e 100644 --- a/.github/ISSUE_TEMPLATE/Feature_request.md +++ b/.github/ISSUE_TEMPLATE/Feature_request.md @@ -3,7 +3,7 @@ name: Feature request about: Suggest an idea for this project --- -Be sure to check the existing issues (both open and closed!). +Be sure to check the existing issues (both open and closed!), and make sure you are running the latest version of Pipenv. If you're requesting a new feature or leaving feedback, please use this forum instead: