Comment by smcl | Hacker News Reader

Comment by smcl | Hacker News Reader

I've never encountered the "X requires unstated requirement Y, which fails to build because of obscure compiler error" issue, I would have liked if the author named X and Y.

However the documentation is totally a fair point. The "re" module is an excellent example - it starts off with a handful of relatively verbose introductory paragraphs and then dives straight into an extremely comprehensive list of special characters. The good news is that all the information you need is there somewhere but sadly it's hard to get there. Another commenter pointed out the Table of Contents, which for some reason my eyes just completely ignore by default. Maybe the font colour doesn't contrast with the background (aquamarine-ish on blue) or the line-spacing makes it tough. Certainly the numbered prefixes do not help, or the fact that the headings aren't actually particularly useful (sorry if you're responsible for the documentation, I like it overall I'm just searching for reasons why it's hard to read the side-menu).

I wish I had the time to help out, and the UX know-how to contribute to making it better. I'd feel awful if I pitched in and made things worse :(

> I've never encountered the "X requires unstated requirement Y, which fails to build because of obscure compiler error" issue, I would have liked if the author named X and Y.

I maintain an open source Python project that tends to attract non-programmers or beginner programmers. This happens all the time. Case in point: https://github.com/BurntSushi/nfldb/issues/175

And that's a good case, because the error message is actually pretty nice compared to some others I've seen. But for a beginner user, learning to make the complete connection I wrote in my comment[1] on that thread is totally non-trivial.

[1] - https://github.com/BurntSushi/nfldb/issues/175#issuecomment-...

I tried installing OpenCV2. I needed to get Pip, then I tried to install OpenCV2, but it required a whole bunch of other stuff, which I had to compile, which failed.

Was a very frustrating afternoon.

If on Windows, google Christoph Gohlke's (spelling?) big list of pre-compiled Python modules.

How do I know to do that? Most projects just say "Install OpenCV" or, if you're lucky, give you the step-by-step for doing a pip install. Assuming you already have pip.

I remember the first time I sat down to really do something with python, step 1 was setup a virtual environment...

I never got to step 2 that week

>How do I know to do that?

The answer, unfortunately, is: you don't - at least not from the docs of all libraries you are trying to use. Maybe from some.

I found it by googling - so shared it, since it might help you.

A less than perfect system, I know.

Yes, I remember that installing pip itself was slightly tricky or involved, a while ago. I think they have made it simpler in recent versions, and it also comes pre-installed with some Python versions, likely 3.x and recent versions of 2.x.

Python's packaging system was and is still sometimes somewhat broken. However, it's getting better: compilation related issues are rarer nowadays thanks to the wheel pre-built package format (https://www.python.org/dev/peps/pep-0491/). Another great thing is the manylinux tag (https://www.python.org/dev/peps/pep-0513/) which allows to create portable packages which are compatible with many distributions + contain all required dependencies. For example, I didn't want to compile anymore OpenCV all the time by myself so I made it available as wheel package in PyPI: https://pypi.python.org/pypi/opencv-python

> I've never encountered the "X requires unstated requirement Y, which fails to build because of obscure compiler error" issue, I would have liked if the author named X and Y.

I've encountered this sort of thing plenty; usually it's not a python package that's required, it's a package you need to apt-get, and then another error pops up because that first one wasn't the only thing you needed.

>build because of obscure compiler error

Exactly what I had in mind, I never got such problems at least in installing libraries, how can that be an issue since we have pip?

yes, some badly maintained libraries will have this, but that's the library author's issue and not a problem with Python's pip, on the contrary pip is working exactly fine if it complains.

Reply on news.ycombinator.com