Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs to explain how to use Python 3 #7368

Closed
wants to merge 2 commits into from

Conversation

Projects
2 participants
@Eric-Arellano
Copy link
Contributor

commented Mar 12, 2019

Problem

#7197 is adding support for releasing Py3 and pantsbuild/setup#32 is modifying our run script we distribute to allow choosing Py3. Meanwhile, we need this PR to update the docs according to the plan laid out in pantsbuild/setup#30.

Solution

Explain how to pin the version. This is the first command we have the user do after curl, because we want them to have the Python version chosen before running Pants and setting up their venv.

Also update the pants version we show.

pants_engine_python_version: 3.6

If you'd like to change which Python version Pants uses, just edit the entry in `pants.ini`.

This comment has been minimized.

Copy link
@Eric-Arellano

Eric-Arellano Mar 12, 2019

Author Contributor

Question #1: do we want this to appear as the first command they do after curl?

Pros:

  • They don't bootstrap multiple virtual environments.
  • More likely users will pin their Python version, which implies more are using Py3 than the default Py27.

Cons:

  • Maybe overwhelming for the user to immediately be confronted with this question, and better to get the program working with ./pants -V and version pinned, then decide to pin interpreter if they want to.
  • If they don't have the default of python2.7 on their system, then ./pants -V will fail to execute.

Note the user can also choose to not pin the interpreter—it will default to Python 2.7.


Then add an entry like so to `pants.ini` with that version:

:::ini
[GLOBAL]
pants_version: 1.0.0
pants_engine_python_version: 3.6

This comment has been minimized.

Copy link
@Eric-Arellano

Eric-Arellano Mar 12, 2019

Author Contributor

Question #2: I want to add these notes still, and am not sure where to put them:

Some notes when choosing an interpreter:
- This does not mean your Python code has to use this same Python version. See https://www.pantsbuild.org/python_readme.html#configure-the-python-version for how to configure your code's compatibility.
- Ensure you have the pinned Python version accessible on your PATH everywhere Pants is used in your organization.
- Pants will require Python 3.6+ to run as of release 1.17.0.

If we move the instruction on pinning lower in the file, past pinning the version, then we can keep those two notes together. Otherwise, is there some sort of gray text box or something I can add that shows it's an aside? I don't want to break the flow but do want to give additional information.

@stuhood
Copy link
Member

left a comment

Thanks!

@@ -59,6 +59,24 @@ NB: The formatting of the plugins list is important; all lines below the `plugin
indented by at least one white space to form logical continuation lines. This is standard for python
ini files, see [[Options|pants('src/docs:options')]].

Pants' runtime Python interpreter
---------------------------------
Pants may be ran with Python 2.7, 3.6, or 3.7. The `./pants` script defaults to using Python 2.7. It's recommeded, though, that you pin the version you'd like to use.

This comment has been minimized.

Copy link
@stuhood

stuhood Mar 14, 2019

Member

recommended

---------------------------------
Pants may be ran with Python 2.7, 3.6, or 3.7. The `./pants` script defaults to using Python 2.7. It's recommeded, though, that you pin the version you'd like to use.

To do this, add an entry like so to `pants.ini`, choosing between `2.7`, `3.6`, or `3.7`.

This comment has been minimized.

Copy link
@stuhood

stuhood Mar 14, 2019

Member

It would be nice to improve the symmetry between the pants_version pinning section and this section (or even merge them?)... unfortunately, I think that doing that would require adding an equivalent of ./pants -v that would render the python version it is running under... or some black magic in the setup script to dump that info and exit..?

@Eric-Arellano

This comment has been minimized.

Copy link
Contributor Author

commented Mar 14, 2019

Going to close this and revisit before releasing 1.15.0, as we shouldn't update the docs before then per https://pantsbuild.slack.com/archives/CBNMV1LRH/p1552535884071700.

Hopefully by then, we will have modified the setup repo's ./pants to auto-initialize pants.ini, so we'll be able to simplify these docs and give less decision paralysis to users.

@Eric-Arellano Eric-Arellano deleted the Eric-Arellano:py3-docs branch Mar 14, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.