Documentation change: easy_install to pip

[stevepiercy]

Update the documentation to use pip instead of easy_install.

Work should be pushed to the branch docs/easy-install-to-pip.2104.

Branch docs/easy-install-to-pip.2104 will eventually be merged to master upon completion of the items listed below.

Add omitted items to the lists.

List of related issues and PRs.

• Spend more time describing packaging, easy_install, pip, and the like. #575
• mod_wsgi deployment should be updated to use pip and verified #1454
• pyramid should have a MANIFEST.in #121
• alchemy scaffold updates #2024

List of documentation and official tutorials

(Pretty much every step for tutorials needs updating, so only the indices are shown for brevity.)

• Glossary
• Quick Tour
• Quick Tutorial
• SQLAlchemy + URL Dispatch Wiki Tutorial
• ZODB + Traversal Wiki Tutorial
• Running a Pyramid Application under mod_wsgi
• narr/commandline.rst
• narr/extending.rst
• narr/installation.html
• narr/project.rst
• narr/testing.rst

[mmerickel]

A couple notes on how to do this:

1. $VENV/bin/python setup.py develop is now $VENV/bin/pip install -e . (the . on the end is important).
2. $VENV/bin/python setup.py install is now $VENV/bin/pip install .

One big issue when updating to pip is that python setup.py test is no longer a great option for running tests. Specifically because the tests_require option will be installed using setuptools/easy_install instead of pip. We need to come up with a common pattern for this.

Three options (please chime in with some alternatives) I'm aware of that would work alright:

1. Add a testing extras to setup.py and show people how to install them with $VENV/bin/pip install -e ".[testing]". They can then continue running their tests with $VENV/bin/python setup.py test.

   Pros: The testing extras is a good pattern.
   Cons: The python setup.py test will try to install (using setuptools instead of pip) any missing dependencies if someone forgot to run -e ".[testing]".

2. Use tox to define the dependencies in a tox.ini and recommend people run tox to start the tests.

   Pros: Tox is great, and encapsulated, and uses pip by default.
   Cons: Most non-library-authors are probably less excited about using tox in their projects and is a larger change from what they were doing before.

3. Add a testing extras to setup.py and show people $VENV/bin/pip install -e ".[testing]" and advocate running the tests with $VENV/bin/nosetests.

   Pros: This is probably the best way to go. It removes setup.py from the equation entirely as a top-level executable.
   Cons: Requires us to define a test runner versus using setuptools' discovery mechanism. It's possible to avoid dependencies on nose or py.test by using python's default unittest runner ($VENV/bin/python -m unittest discover) but it's a little kludgey and only available in 2.7+ (not 2.6). This means we'd want to add a dependency on nose or py.test (my personal choice). However this may not sit well with people.

Let's talk about it and come to some conclusions so we can migrate everything consistently.

Update: Thanks @mgrbyte I updated the examples with quotes.

[pauleveritt]

Geez, the number of things I don’t know. .[testing] ? Really? I’ve read all this stuff numerous times.

My two cents, for what it’s worth:

• The switch to pip is about recognizing that our docs need to appeal to people using mainstream Python choices
• Stated differently, if they expect pip, and we give easy_install, we’re the weird ones, not them (despite our valid protests)
• I feel the same about my personal switch to jinja2 for all teaching material

That said, I don’t think there’s a strong majority that is doing this a certain way. I personally don’t see many docs out there showing test running via setup.py. I think py.test is perhaps a cooler-kid on the block than nose, but not overwhelmingly (though it does seem more active.)

So I vote for (3) with py.test, caveat that it means fixing a lot of docs away from nose.

Regarding best practices, any implications on how Travis works? Does it sniff at setup.py to discover what to run, or does it just do what you tell it in the YAML file?

—Paul

On Nov 11, 2015, at 12:22 PM, Michael Merickel [email protected] wrote:

A couple notes on how to do this:

$VENV/bin/python setup.py develop is now $VENV/bin/pip install -e . (the . on the end is important).
$VENV/bin/python setup.py install is now `$VENV/bin/pip install .
One big issue when updating to pip is that python setup.py test is no longer a great option for running tests. Specifically because the tests_require option will be installed using setuptools/easy_install instead of pip. We need to come up with a common pattern for this.

Two options (please chime in with some alternatives) I'm aware of that would work alright:

Add a testing extras to setup.py and show people how to install them with $VENV/bin/pip install -e .[testing]. They can then continue running their tests with $VENV/bin/python setup.py test.

Pros: The testing extras is a good pattern.
Cons: The python setup.py test will try to install (using setuptools instead of pip) any missing dependencies if someone forgot to run -e .[testing].

Use tox to define the dependencies in a tox.ini and recommend people run tox to start the tests.

Pros: Tox is great, and encapsulated, and uses pip by default.
Cons: Most non-library-authors are probably less excited about using tox in their projects and is a larger change from what they were doing before.

Add a testing extras to setup.py and show people $VENV/bin/pip install -e .[testing] and advocate running the tests with $VENV/bin/nosetests.

Pros: This is probably the best way to go. It removes setup.py from the equation entirely as a top-level executable.
Cons: Requires us to define a test runner versus using setuptools' discovery mechanism. It's possible to avoid dependencies on nose or py.test by using python's default unittest runner https://docs.python.org/2/library/unittest.html#test-discovery but it's a little kludgey and only available in 2.7+ (not 2.6). This means we'd want to add a dependency on nose or py.test (my personal choice). However this may not sit will with people.

Let's talk about it and come to some conclusions so we can migrate everything consistently.

—
Reply to this email directly or view it on GitHub #2104 (comment).

[mgrbyte]

Not being a regular contributor, not sure my vote counts....
but my 2p (British money...) is same as Paul (option 3 w/py.test instead of nose)

One caveat - when using the zsh shell, you need to quote the extras, i.e:

pip install --editable ".[testing]" 

(this also works in bash)

[blaflamme]

I'm for #3 too.

[mmerickel]

@dstufft I'd love to hear your thoughts on test runners and tests_require usage in this brave new world. My impression is that tests_require and test_suite should no longer be used and focus on using setup.py as the metadata description/build system rather than the runner.

[dstufft]

I normally do a combination of all three, I define a test extra and I have the same list being sent into both that extra and the tests_require keyword. I tend to override the test command to use py.test as well and then I pretty much always just run the tests using tox :).

That being said, the story around a standard interface for running tests (other than a sort of defacto stand off between tox and setup.py test) isn't great right now. It's mostly about picking tradeoffs right now :(

[digitalresistor]

I tend to use py.test for all of my testing, run through tox. This way I can build documentation and everything else along those lines automatically as well.

[jvanasco]

I would just really love it if package maintainers would simply make a top-level TESTS.txt that documents how the tests are organized and invoked, and gives pointers on how to customize testing for feature development or bugfixing.

In the past 12 months, I've contributed patches + tests to at least that many python projects. No two projects have taken the same approach to tests, and many people use "bleeding edge" test harnesses that look like they should be invoked one way, but really want to be used another (ie, if you run via setup.py then suites a+b+c will run... if you run via something else d+e+f will run, and if you run via a 3rd option a+b+c+d+e+f will run). I've had to learn way more testing frameworks and random implementations than I'd like.

So whatever you choose, please please please just make a TESTS.txt file that at least says:

• We use ___ for tests.
• You can invoke the full testing suite by doing this _____
• If you'd like to run a subset of tests to isolate an issue or fix, you should do _______
• When writing new tests, we prefer ______

and give a few examples.

If you can convey that information (and maybe a few other things) and keep it up-to-date, many people will be exceptionally happy.

[tseaver]

@jvanasco maybe you mean this?

[digitalresistor]

@tseaver 👍

[jvanasco]

@tseaver I've never noticed that before! I really didn't expect it in a "HACKING" file. It would be great if it were somehow pointed to in the README and highlighted at the top of that file (ie, a TOC of what's in that). An example for the individual test would be great too. I'm really biased to this sort of stuff being "super obvious".

[stevepiercy]

See also https://github.com/Pylons/pyramid/blob/master/contributing.md#prerequisites which appears as a friendly yellow reminder whenever you report an issue or submit a PR.

All that said, I agree with @jvanasco. "HACKING" is not an intuitive name. I recall I had the same problem when I was trying to get started with Pyramid. I usually check the README first. I'll add a section to the README, and roll it down to 1.5.

[jvanasco]

@stevepiercy maybe something like this in the README ?

Running Tests and Development
-----------------------------

See the `HACKING.rst` file to learn how Pyramid runs tests and developer tips 
and requirements when contributing to this project.

[digitalresistor]

As a developer on a huge variety of projects over the years. HACKING is very often used as the file name for developers that want to "hack" on the project. I don't find it that unintuitive.

[marioidival]

Guys, I never used Windows and Python together, you can see if this snippet is correct?

    c:\\> c:\\Python33\\python -m venv env33
    c:\\> env33\\Scripts\\activate
    c:\\> pip install "pyramid==\ |release|\ "

Snippet in pyramid/docs/quick_tour.rst

[mmerickel]

@marioidival please don't hijack this ticket, it isn't the appropriate place for support questions (the mailing list is). You can see in http://docs.pylonsproject.org/projects/pyramid/en/1.6-branch/quick_tour.html that the RST source is rendered out as pyramid==1.6, not "pyramid==\ |release|\ ".

[stevepiercy]

@marioidival it renders as:

c:\> c:\Python33\python -m venv env33
c:\> env33\Scripts\python ez_setup.py
c:\> env33\Scripts\easy_install "pyramid==1.6"

See rendered result: http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tour.html#installation

See also the rst directive parsed-literal.

[marioidival]

@mmerickel Here is the correct place so, why am I doing this PR, started programming using UNIX environments and as I said before, never used Windows, I wonder how to do so correctly to proceed.

[Themanwithoutaplan]

1. tox + requirements.txt inflating setup.py with optional dependencies makes things unnecessarily complicated.

[stevepiercy]

@mmerickel @dstufft's article suggests a fourth option (NB: I am not a package manager, nor do I play one on television.)

# requirements.txt
--index-url https://pypi.python.org/pyramid/

-e .

which would be invoked by pip install -r requirements.txt.

That pattern could be repeated for tests-requirements.txt, docs-requirements.txt, and any other purpose.

I think that's what @Themanwithoutaplan meant.

[edited per @Themanwithoutaplan comment below]

[Themanwithoutaplan]

setup.py must still have the packages required for the library. Outside of a testing_requirements.txt which is useful for a test-runner without invoking tox (a very common pattern), I wouldn't want any additional requirements files because everything can be driven by tox, unless tox uses them too. This is a clearer separation of responsibilities.

[digitalresistor]

What? I hate requirements.txt, I hate the fact that it means now I need to run pip install -e . and then pip install -r requirements.txt to get started on a project.

pip install -e .[testing] also makes sense to me. Keep everything in one place, don't try and "split responsibilities".

[stevepiercy]

Whoa, I don't know what I did, but somehow this issue got closed. Reopening.

The branch for this work is now https://github.com/Pylons/pyramid/tree/docs/easy-install-to-pip.2104

[stevepiercy]

While working on the wiki2 tutorial, I edited the default setup.py file in order to install test requirements as @mmerickel described in Option 3.

1. Should I roll changes in setup.py into the alchemy scaffold or just leave them in the wiki2 tutorial?

[Themanwithoutaplan]

-1 on testing requirements in setup.py for the usual reasons: a tox config is much more flexible and in any case required for serious testing.

If you're going to following the pytest recommendations then add a pytest.ini (norecursedirs is a life-saver) as this makes the test discovery pattern explicit.

[stevepiercy]

@Themanwithoutaplan I scratched the pytest recommendations because some people like to group tests in a single file, others by folder, and others by feature. Better not to exert an opinion on this one.

As far as tox or setup.py is used, I have no opinion other than going with the prevailing opinion, which is currently Option 3, so that's what I'm documenting.

Of course, if the wind should change, I can go with tox.

[stevepiercy]

See PR #2442 for the rough draft of setup.py for Option 3.

[jvanasco]

I just created a project using that forthcoming scaffold.
The tests starter would have been great.

On Apr 8, 2016, at 6:33 AM, Steve Piercy [email protected] wrote:

While working on the wiki2 tutorial, I edited the default setup.py file in order to install test requirements as @mmerickel described in Option 3.

Should I roll changes in setup.py into the alchemy scaffold or just leave them in the wiki2 tutorial?
While I'm at it—and because the wiki2 tutorial ends up using this structure anyway—should I use the Conventions for Python test discovery, i.e.,
tests/
init.py
test_default.py
I'm leaning toward rolling these changes into the scaffold so that it provides a good example of how to get started.

Let me know what y'all think.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub

[digitalresistor]

@Themanwithoutaplan we currently don't provide a tox.ini in our projects, and I don't think we should add that as yet another thing in the scaffold.

I am a +1 on option 3, adding testing extra's makes sense, and is a built-in functionality that exists specifically for adding extra dependencies.

[digitalresistor]

@stevepiercy I do think you should roll them back into the scaffold.

[tseaver]

tox is hugely important for library developers, who need to ensure that their tests run easily on all supported Python versions / implementations. I'm not convinced that tox is a huge win for the kind of apps we expect people to build with the scaffolds: "bespoke" apps tend to be deployed only for a single Python version, for instance, which negates the main advantage of tox over other testing styles.

[pauleveritt]

I'm also -1 on tox. Scaffolds are (primarily) for new folks. Handing them another thing to learn and deal with should be kept to a minimum. In JS/Yeoman, a lot of scaffolds have a dozen flavor-of-the-week JS project/tools in them, and the scaffold winds up being brittle magic.

[Themanwithoutaplan]

Even though I introduced it to the discussion, debate about tox is a bit of a red herring. To mix my food metaphors: the old issues of a testing clause versus testing_requirements.txt is really about what kind of cheese people are used to. As I still struggle with writing setup.py but can reliably produce and manage requirements files this is why I'm in favour of them. Adding options to setup.py adds complexity which I think the incantation exposes: try and explain that to anyone new.

But I'm happy to be in my minority of one. I usually am. :-)

[stevepiercy]

I've hit a roadblock on the Installation chapter: installation of setuptools and virtualenv. I could use some clarity from the experienced folks.

I'm not sure how to rewrite these two sections. I'm inclined to prioritize Python 3.4+, with exceptions to the priority.

• For Python 3.4+, both setuptools and virtualenv are already installed.
• For Python 3.3... ?
• For Python 2.7... ?
• For Python 2.6... ?

[stevepiercy]

A huge, major, ginormous change for Installation of Pyramid is now in PR #2466. I'm going to let this one simmer for a while for discussion.

[stevepiercy]

I'm DONE! whew! See #2468.

[stevepiercy]

Closed by #2468