
This Is What Python Beginners Have to Deal With - reubano
http://pythonforengineers.com/this-is-what-python-beginners-have-to-deal-with/
======
junke
> Now, compare that to what happens when I search for the same in Python. I
> get this:

>
> [https://docs.python.org/2/library/re.html](https://docs.python.org/2/library/re.html)

I clicked and I saw the kind of technical documentation I love to read:
precise, with examples. There is an introduction to Python's flavor of regular
expressions, which highlights the potential problems (backslashes). This is
not targetted at novice _programmers_ , though.

> That’s the generic re library page. I have to scroll down to see which
> function I need.

Did you notice the table of contents on the left? You might want to try
Ctrl+F. But you might have to scroll down too, I don't deny it. You have to
read, too.

> And even then, all I get is a hundred words of generic description. No
> examples.

Ctrl+F "example" highlights the table of contents. There is an example for
"findall".

> I then have to Google Python regex findall examples, and go through a dozen
> blogs written in 2008.

[http://lmgtfy.com/?q=regex+findall+example#](http://lmgtfy.com/?q=regex+findall+example#)

Not really, there are plenty of recent posts (stackoverflow, etc). And having
articles from 2008 would not even imply that they are incorrect. In order to
see how old your post is, I have to look at the source, but even though it is
quite recent, it contains factual errors.

~~~
Illniyar
I think this is the exact type of comments that the author comes out against.

You aren't putting yourself in the shoes of a beginner.

Let's say I'm a beginner, and I want to just experiment with the language a
bit (I've already read some tutorials or am not interested) - since I'm just
trying to get the feel of the language and ecosystem, I'm not trying to get a
deep understanding of the language and tools - I want to match a regex.

In the C++ and PHP examples he provided, the basic example is easily found -
it's basically two actions - search in google and scroll to the example.

What you are suggesting takes several more steps - ctrl-f for a text that you
might get wrong (you've searched for sample instead of example for instance),
iterate until you get the right place, etc...

And that's assuming you even realize that you should run ctrl-f, why should
you?

The main issue though is that if I'm a beginner I'm doing this kind of
searches several times a minute - to have to stop and realize what to look for
every time is extremely frustrating.

I've worked with Ruby,Python, Java and Javascript - python's (and django's)
documentation is extremely verbose and rarely straightforward compared to the
other ones.

~~~
junke
> You aren't putting yourself in the shoes of a beginner.

How do you know if I am putting myself in the shoes of a beginner or not? And
what kind of beginners are we talking about? Are they comfortable with a
browser? Do they already know how to program something? You can't expect a
single document to be relevant for all kind of people. The reference
documentation has a clear target audience, which apparently conflicts with
what you expect from it.

> And that's assuming you even realize that you should run ctrl-f, why should
> you?

> (you've searched for sample instead of example for instance)

Okay, so you are talking about absolute beginners, with no experience
whatsoever with programming. And the C++ and PHP pages are somewhat useful for
them?

> I've already read some tutorials or am not interested

> Let's say I'm a beginner [...] I want to match a regex.

Now, you are saying that you already have experience with programming? Google
"python tutorial regex" gives plenty of results, the first of them being
currently "Regular Expressions HOWTO"
([https://docs.python.org/2/howto/regex.html](https://docs.python.org/2/howto/regex.html)).

Absolute beginners need a teacher, a mentor, or a step-by-step book, or a very
gentle tutorial, or an online REPL. That's fine. You can't please everybody in
the reference documentation.

~~~
userbinator
_And what kind of beginners are we talking about? Are they comfortable with a
browser? Do they already know how to program something?_

I'll add to that, "Are they even _computer-literate_ in any way?" I'd worked
at a college a few years ago, and it is sometimes shocking how little the
newcomers know about just using and troubleshooting basic problems with
computers, nevermind learning how to write programs for one... and IMHO it's
only gotten worse. Knowledge of things like basic filesystem concepts ("What's
a directory? How do paths work?") in particular seem to be disappearing.

------
arximboldi
You know what puts off beginners?

Articles plagued with stuff like "this is horrible", "this is shit" and so on
and son.

I see too often articles that just try to denigrate other technologies, saying
that they suck, they are horrible, they are shit, they should be considered
harmful, etc, just to try to make the author sound smart-assed.

The truth is that most stuff is the way it is for a reason. Maybe the
situation has evolved and the reason is no longer valid, or maybe the people
that built the thing had different goals than you. But understanding why it
was valid for the other person and why it is maybe not valid for your use-case
in an empathetic way will only make you a better engineer. We are all smart
people trying our best to achieve something using technology. We are on the
same boat. Let's stop insulting each-other.

If I was a novice and saw and article like this, I don't think I would want to
hang out with such an overreacting crowd. Python is a libre project: instead
of insulting other people's work to sell your book, try improving it. I can
understand why proprietary software sometimes sucks -- it is disempowering --
but with libre software you are just kindly given a gift. If you don't like
it, improve it and give back to the community, don't denigrate.

~~~
uola
Many people have been and are contributing. But when there isn't critical mass
or appreciation for changes they move on to other things. So the python
community is not only left with the flaws but can't attract people to fix
them.

------
stevetrewick
I pick Python up maybe 3 or 4 times a year - usually to automate something or
to explore some algorithm in a notebook - so I'm pretty much an eternal
beginner (in respect of the language, rather than the development process).
This means I'm hitting up the docs pretty much constantly and I do find them
mildly frustrating. It's an organisation thing. As someone stated up thread,
the docs are really comprehensive, which means they resist skimming. There's
no distinction between - say - a language _guide_ and a language _reference_.
As someone coming at Python from a comprehensive background in other PLs I
just want to see a damn example, I don't want or need to read a treatise on
operator precedence or regex syntax. Fortunately this problem is easily solved
by adding the word 'example' as a search term - and then going back to the
super comprehensive docs to find out what I just did wrong with my regex
syntax!

For a _complete_ beginner, the documentation for most any language is just
line noise at first, until you gain the appropriate context (for which there
are a pile of easily googleable resources) and thereafter the more
comprehensive the better because you don't know _what you don 't know_.

Maybe if there weren't eleventy bajillion easily accessible 'how to X in
Python' articles or SO wasn't a thing there would be some pressing need for
differently organised docs, but there are and it is, so y'know, meh.

Edit: over opinionated autocorrect.

------
sillysaurus3
I think the Python docs are fine. I use them all the time. (The re docs in
particular.)

It's not beginner-focused, but it'd suck if the current docs were replaced
with docs for beginners.

The re page has over 7,000 words. I need those 7k words. They help me get
things done.

Perhaps a solution might be something like a
[https://simple.docs.python.org](https://simple.docs.python.org) type site: A
simplified version, parallel to the existing documentation, consisting mostly
of examples. I'd use it.

~~~
mrweasel
The issue with the Python docs is that you have to ACTUALLY READ IT. Some
language have documentation that you can just sort of skim and pick out the
bits you think you need.

The Python documentation, and the Django documentation have additional
information in the text. Describing how a module or function works, what you
can expect and how you should use it. Important information is often "hidden"
in the text and if you're the sort of person that doesn't actually read the
documentation you're going to get it wrong.

The Python docs are absolutely fine, because actually tries to teach you how
stuff works and why it is the way it is.

~~~
tgwallace
I think the docs are often too verbose. Many pages start with a long winded
intro that misses the main point. Some pages never get to the point.
Docstrings are sometimes several pages long.

Example of not getting to the point: Extending/Embedding.

There is no fundamental difference. In both cases you're just calling a bunch
of functions from libpython.a.

------
smcl
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_ :(

~~~
edent
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.

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

~~~
edent
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.

~~~
Klathmon
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

------
partycoder
The typical narrative of the mediocre duct tape engineer.

"I want to put something together fast by trial and error, without having to
go through actual thinking or understanding. I don't care about details, just
give me an example that I can copy, paste and duct-tape with another piece of
code, so I can ship my product and charge some idiot a fortune for some
spaghetti with meatballs code."

Documentation does not necessarily have to follow the format of a tutorial and
can vary in levels of detail. Tutorials on this topic do exist. There, LMGTFY:
[https://docs.python.org/3/howto/regex.html](https://docs.python.org/3/howto/regex.html)

How did I find it? Google: regular expression site:python.org

~~~
iaskwhy
Is it really wrong to learn something new with examples and without having to
read a full book before typing the first few lines of code? I prefer to learn
by trial and error.

~~~
partycoder
It is a valid option to explore by trial and error. But once you have obtained
something that seems to work, if you can't explain why it is working, it is a
bad moment to stop.

If you construct an entire system by trial and error without an understanding
of how and why it's working, you are exposing yourself and your customer to
serious risks.

Even if things do not crash, if your code gets audited (e.g: when another
person joins your team), you will have a bad time explaining your choices. As
a professional engineer, it is expected of you to know what you are doing, and
fudging code is the easiest way of getting sacked to the sound of a trumpet.

~~~
iaskwhy
Right but the article was about a beginner learning a new language, I don't
think a beginner is expected to have audit-proof code for quite some time.

------
pbhjpbhj
I've been learning Python as it seems to be the preferred language in
education at the moment in UK and I'm expecting my kids to be using it. I work
in arts & craft but have a strong hobby background in computers.

I started with a Coursera course
[https://www.coursera.org/learn/python](https://www.coursera.org/learn/python)
which was pretty easy (you can run the videos at 1.5 or 2x).

That course is based on a free gratis book by the lecturer (there a chapter on
regex that covers re; with examples too).

I took a good few hours trying different IDEs and settled on PyCharm community
edition, it has very easy doc lookup. ([http://alicious.com/editors-ides-
python-code/](http://alicious.com/editors-ides-python-code/) is a brief
summary of most of my IDE-for-python search.)

Currently I'm doing the Web Data course (using Beautiful Soup) and the only
problem but is that _by choice_ I'm using Python 3 when the course is written
for 2. It covers regex pretty well.

------
rtpg
I'm kinda surprised about the community argument. I've generally felt that
people are nice enough, if a bit conservative. Though I guess this is the
community that produced Python 3k, so something must have gone wrong

Especially to hear that someone went from Python to Ruby... I still feel raw
for getting yelled at in IRC for trying to understand how blocks differ from
anon. functions and about not doing things the "Ruby way"

~~~
jbmorgado
I also found that part odd.

At least in stackoverflow, compared to R community, I found python community
to be more helpful and more polite.

~~~
dkersten
Agreed. The community is the part I like most about Python. I've largely
stopped attending talks and such years ago, but still attend events every now
and again (mostly the annual local conference) purely because I find the
community friendly and interesting.

------
the_mitsuhiko
I feel a big problem with Python these days is that it's not one Python
community. It really is becoming more and more fractured and efforts go into
weird places.

For instance we have the core developers which do Python 3, then we have some
separate volunteers that work on the packaging infrastructure which is largely
based on cobbling systems on top of the horribly broken distutils/setuptools
setup. For documentation people don't want to touch it that much because which
version should it go in? Python 2 which everybody is using or Python 3?

This schism in the community is causing more and more issues as time goes on.

------
gaius
An odd article; the site is adware for a book, if the documentation was better
he or she wouldn't have any sales!

------
devnonymous
2 out of the 3 negative points talks about how horrible the documentation is
and yet I almost every day see blog posts, tutorials, books etc being posted
online. If it really is so horrible why are these 'authors' apparently, not
contributing to those horrible docs to make them better?

The gripe about packaging however is justified in a small manner, although we
are way better than we used to be.

~~~
em500
> If it really is so horrible why are these 'authors' apparently, not
> contributing to those horrible docs to make them better?

Incentives (building their personal brand) is much more tilted towards blog
posts, tutorials, books etc. than improving the standard documentation.

~~~
cderwin
But if you're complaining primarily to further your personal brand (not
because you genuinely want to see a problem addressed), why should your
complaints even be taken with merit?

------
Houshalter
Once there was a discussion on HN about a specific command line tool, how easy
command lines were and how even an idiot should be able to install and use it.
I decided to test that theory by attempting to install it on a fresh copy of
Windows, and documenting every step. I did get it installed, but did not
succeed in using the command line tool for the desired application. There was
also a number of difficult steps that nontechnical users would not know
anything about and get frustrated by or turned away from. There were serious
mistakes in the instructions. The biggest issue was dependencies which had
further dependencies, all of which had their own difficult installation
instructions. At least it didn't require compiling anything!

[https://news.ycombinator.com/item?id=11453086](https://news.ycombinator.com/item?id=11453086)

------
ForFreedom
The trouble I had installing numpy, scipy and theano on python was over 3 days
and only numpy & theano works.

3 days to go over the internet find out what the error... then trial and
error.

Yes its difficult. And as the author says,"people get down voted"

------
ap22213
Remember that Python is several decades old, and version 2 is about 16 years
old. Like UNIX man pages, the docs (as well as best practices, idioms, etc.)
were influenced by programming methods of the day. There was much more time to
read the docs, think, and experiment. There weren't many answers to be found.

The methods of the modern developer are much different: 1) run into problem,
2) look for library to solve problem, 3) install library from package manager,
4) look for examples of library that fit problem, 5) copy-paste-modify
example, 6) commit.

I can see why the docs are insufficient for today's beginners.

~~~
Eridrus
PHP is just as old and when I learnt PHP 14 years ago the docs were really
friendly back then too, I loved being able to go to php.net/func_name and get
a good description of how it worked. Of course this is for the standard
library, which is what the article talks about, but PHP's standard library (at
least then) had much more of the kitchen sink thrown in it.

------
lkiux
If python documentation is bad then, god forbid, these poor users should try
to use anything else such as node.

As far as technical documentation does, the python documentation is usually
ranging from pretty good to very good.

------
mickmock
I can't believe an advertisement has gotten so many up votes.

The only problem I had when learning python is that it took me a while to
figure out that you have to put __init__.py in every folder. Easiest language
I've ever learned and made projects with, and I had previously learned
Java/C/C++/Erlang

------
raverbashing
1st problem, do pip install pip --upgrade in your virtualenv as the 1st thing.
Another possible solution, install the corresponding .rpm/.deb package

2nd problem: go to this page first [https://docs.python.org/3/py-
modindex.html](https://docs.python.org/3/py-modindex.html)

3rd problem: yeah, kind of. Except for the logging module. Eff the logging
module, it's a "java made in python" crap

~~~
talideon
Structlog FTW!

I only use the logging module these days when I've no alternative. The API for
configuring logging is terrible.

------
thewhitetulip
>Installing libraries

I think pip and easy_install solves this problem. Or did I read the point
incorrectly?

>docs are horrible

Also I never had seen the JS documentation of Mozilla, it is just beautiful. I
have been using Python without any documentation related problems for that
time, I actually am fond of Python documentation, for some reason it struck a
chord with me.

The thing is, I learned Python by using the docs as the starting point,
studied the tutorial and later the standard library, never really had a
problem sorting through the docs ever. For everything there is a global module
index, go to the a-z, click on a, go to the respective class/function and it
has a good example, at least for the stdlib

I love Go language's docs more though.

~~~
richardwhiuk
Try "pip install pycurl". It'll fail. The solution is to install a C compiler
and (on Ubuntu) run apt-get install libcurl4-openssl-dev. That's very
different to other languages - they don't expect you to have a bunch of
different development environments.

~~~
Illniyar
That's not really true, lots of languages requires certain modules to be built
from source with a C compiler.

Ruby and Node.js comes to mind.

Though in general the community behind them do a much better job of hiding
this complexity from the user - to the point that most times you don't realize
you've compiled it from source.

------
afarrell
Is there a good place to go for critiques on your project's documentation?

I'm currently working on updating the API docs for the company I work for, so
we're paying people. However, what should open source projects do?

One thing I've seen that works poorly is encouraging new contributors should
work on the documentation. The problem with this is that a new user only has
knowledge of what they are confused by--not the broad understanding of the
project that allows them to compose a document that teaches a coherent mental
model. It seems like that can only be done by someone who is familiar with the
project, but then they need a way to test that their writing actually makes
sense.

------
willyt
I really like python, I use it all the time now and I don't start any new
stuff in Ruby. But it was a struggle to get over the hump. I pretty much never
use the Python docs, for the author's example, I would just google 'python
array length stackoverflow'. I would only look at the official docs if
something piqued my interest and I wanted to know more. Whereas with Ruby I go
straight to chapter 4 of the pickaxe book and it answers the question 99 times
out of 100. Also because its a PDF it works reliably on the train! I would
dearly love to find a similarly written reference for python.

~~~
talideon
I'm not sure if this is what you're looking for, but Sphinx, which is used for
generating the Python docs, is capable of producing docs in a number of
formats, including ePub and PDF, and offline versions of the docs have been
available for download in those formats ever since the changeover to Sphinx:
[https://docs.python.org/3/download.html](https://docs.python.org/3/download.html)

------
crdoconnor
1) is really something that the maintainers of pip should deal with but
unfortunately they don't see it as their problem.

~~~
talideon
I really don't know of anything like pip that can handle that case in any
language, and I'm not entirely convinced that somehow resolving the plethora
of naming conventions for packages between different distros (and even
different _vesions_ of those distros) is really the job of a language-specific
package manager.

Nobody's done it because any potential solutions are much too brittle. On
Debian derivatives, it's not too big a problem, but go outside of that, and
even high-level tooling is a mess (the tooling on top of RPM varies from
distro to distro, and even version to version). On macOS, if you're using a
ports-like system, you might be dealing with fink, MacPorts, brew, pkgsrc, &c.

Any competently-managed project, OTOH, will list the dependencies for a number
of major distros and OSs so that the person installing it will have an idea
what to look for.

I'm all ears for a reasonable solution to this, if you have one.

~~~
crdoconnor
>I really don't know of anything like pip that can handle that case in any
language, and I'm not entirely convinced that somehow resolving the plethora
of naming conventions for packages between different distros (and even
different vesions of those distros) is really the job of a language-specific
package manager.

I actually started probably the only project to actually make a stab at
solving this:
[https://github.com/unixpackage/unixpackage](https://github.com/unixpackage/unixpackage)

However, I'm loath to continue working on it because there are few tasks more
tedious, filled with annoying edge cases and thankless than this. Plus I know
it would never make it into pip because "it's not pip's job".

>I'm all ears for a reasonable solution to this, if you have one.

The only one I can think of is to packages like libpq-dev and libjpeg-dev and
even the C compiler installable via pip and get the maintainers of
pillow/psycopg2/whatever else to remove all their horrible hacky code to look
for these dependencies on the system itself.

This will balloon the size of virtualenvs and increase installation times but
it'll be worth it. Not only will it eliminate those horrible installation
errors making everybody happy (not just beginners), it will eliminate a nasty
source of brittleness (subtly different behavior caused by different versions
of these packages on different platforms).

~~~
talideon
> However, I'm loath to continue working on it because there are few tasks
> more tedious, filled with annoying edge cases and thankless than this.

That, in a nutshell, is the problem.

> Plus I know it would never make it into pip because "it's not pip's job".

There are good reasons it wouldn't make it into pip: something like that is
more the realm of setuptools, rather than pip.

> The only one I can think of is to packages like libpq-dev and libjpeg-dev
> and even the C compiler installable via pip and get the maintainers of
> pillow/psycopg2/whatever else to remove all their horrible hacky code to
> look for these dependencies on the system itself.

The 'horrible hacky code' is autotools 90% of the time, and while I'd like to
see if die in a fire and for pkgconf to replace it as far as library detection
goes, it's not going away any time soon.

Also, there is next to no chance of what you propose happening: you're
essentially proposing a parallel system package management system, and at that
point you'd might as well just propose that the Python packaging toolchain
integrate, I don't know, maybe pkgsrc into itself.

~~~
crdoconnor
>That, in a nutshell, is the problem.

That problem can be solved with money. I've seen Jessica McKellar offer to
shower PSF money over people who want to help make installation of python
easier for beginners on _Windows_. I've not seen her offer to shower money
over anybody wanting to solve this problem.

And, as I mentioned before I don't believe a solution like that unixpackage
would actually make it into pip. They'd refuse it.

 _That_ , in the nutshell, is the problem.

>There are good reasons it wouldn't make it into pip: something like that is
more the realm of setuptools, rather than pip.

Maybe. I'm never really sure where one ends and the other begins, to be
honest. Perhaps that's part of the problem.

>you're essentially proposing a parallel system package management system,

I am, yes. And as ridiculous as that may sound it's utterly crucial.

>and at that point you'd might as well just propose that the Python packaging
toolchain integrate, I don't know, maybe pkgsrc into itself.

That would be my other proposal, yes. Either pkgsrc, guix or nix.

>Also, there is next to no chance of what you propose happening

Want to know what's really shit about python?

~~~
talideon
No, this is a significantly bigger problem than simply getting things to work
well on Windows.

Have you proposed this to anyone in the PSF?

> Maybe. I'm never really sure where one ends and the other begins, to be
> honest. Perhaps that's part of the problem.

In a nutshell, leaving out various details: pip downloads packages, asks them
for their dependencies, downloads the dependencies, asks them for their
dependencies, and so on, and so on. Then it does a topological sort and asks
them to install _themselves_.

The process of installation is done by the setup.py file within the
package[1]. That's setuptools.

The line between the two is pretty clear; this is similar to the split between
dpkg/apt or rpm/yum, except setuptools itself has some built-in dependency
resolution support.

[1] Assuming it's not a wheel.

> I am, yes. And as ridiculous as that may sound it's utterly crucial.

And a security nightmare.

> Want to know what's really shit about python?

Do you know what's shit about dealing with just about every language out
there? Pick a language with its own package management, and the moment it
steps outside of its own runtime environment, this problem crops up.

Want to know why I think there's little chance of this working? It's nothing
to do with Python and everything to do this being a nightmare for sysadmins.

~~~
crdoconnor
>Have you proposed this to anyone in the PSF?

I'm not interested in getting involved in their politics.

>And a security nightmare.

Absurd.

>Do you know what's shit about dealing with just about every language out
there?

Not this. You might have noticed a variety of java programmers saying "nope,
not an issue here".

>Pick a language with its own package management, and the moment it steps
outside of its own runtime environment

The issue is not at all to do with stepping outside of the runtime environment
and everything to do with running code in an uncontrolled environment. The
solution is to control the environment as much as you can and fail cleanly if
you can't.

>Want to know why I think there's little chance of this working?

No, I have no interest in what you think any more.

~~~
talideon
> I'm not interested in getting involved in their politics.

Then why did you even bring them up?

> Absurd.

Not if you're a sysadmin.

> Not this. You might have noticed a variety of java programmers saying "nope,
> not an issue here".

Because JNI is barely used. This isn't the case with Python, or Ruby, or a
host of other lanuages.

> No, I have no interest in what you think any more.

Don't be an ass.

------
faraggi
I see many people like python docs, and I agree, but the article talks about
the difficulty for __beginners__.

That being said, maybe the python docs need something equivalent of
wikipedia's 'Simple English' definitions.

Maybe by adding a 'simple' prefix (ie:
simple.docs.python.org/3.5/library/re.html) that takes us to the very
simplified version of the current documentation. Links to the in-depth docs
are obviously necessary as well.

~~~
hjnilsson
The main problem with the python docs is not the verboseness. It's that they
are entirely unstructured. If there just was a standard list of bold parameter
- explanation and finally return value it would help immensely.

My own favorite is urllib.request.urlopen, the description mixes arguments,
return values and exceptions in a blob of text two pages long. It's very
confusing to read if you are a beginner just trying to fetch a file. The
examples are way, way down on the page where you will never find them, the
table of contents is so long you can't even see there is an example section
unless you scroll down the menu.

On the bright side though, everything is explained in the text. It just less
accessible than some other projects' documentation.

------
avyfain
Here's a cached version (thanks, Google!) since the site seems to be down:
[http://webcache.googleusercontent.com/search?q=cache:3GQ0z6z...](http://webcache.googleusercontent.com/search?q=cache:3GQ0z6zB72cJ:pythonforengineers.com/this-
is-what-python-beginners-have-to-deal-with/+&cd=1&hl=en&ct=clnk&gl=us)

------
adontz
>> I tried to install X. But when I ran it, it threw up a generic error, which
meant (after Googling) that it needed Y. Okay. So I installed Y. But Y needed
Z. And Z needs a C/C++ compiler. Okay, I’m on Linux, I have those.

If package maintainer does not specify dependencies, what can be done, really?

~~~
crdoconnor
setup.py doesn't give a consistent mechanism to specify those kinds of
dependencies.

~~~
daenney
How so? Any package in setup.py can declare a install_requires listing,
including version matchers, of its (direct) dependencies. Those dependencies
themselves should take care of listing theirs and so on completing the chain
so that tools like pip can do their job.

That doesn't mean you can't run into a situation where a dependency cannot be
resolved, but I don't see any problems around specifying them.

~~~
heartsucker
I think the author meant packages output of pip, like this issue:

I want to install the pip package cryptography. I need to make sure Python.h
is available. I need to make sure (on Debian) that lib-ffidev and lib-ssldev
are available. This isn't said anywhere by pip (except Python.h, probably),
and it's not the same on every system, let alone every Debian based system.

~~~
daenney
Ah, right, that makes sense. I don't think it's a fair criticism though, as
you're crossing the boundaries between packages provided by your language
ecosystem vs. those provided by your OS (distribution). There's no easy way to
specify this in a way that would work on all platforms or you'd have to start
adding logic to pip that knows how to apt/yum/pacman/port install those
things.

It's the same if you look at Ruby, Node, even Go and many others. The second
you need native libraries/binaries all you have to go on is the hope that the
author has documented them along with the rest of the installation
instructions. The current only way around it is hoping that your distribution
has packaged up the library you need (and is up to date enough for your
requirements) in their native format and declaring the required dependencies.

~~~
crdoconnor
There's two ways around this:

* Provide a way to detect the package or lack thereof and fail in a consistent, easy to understand way. This part actually wouldn't be too hard.

* Provide a way to use the package via nix, guix or pkgsrc instead and enforce its usage so the OS package manager stops mattering. This has the additional benefit that you can specify versions (fairly important since different versions of those dependencies can have far reaching effects).

------
burnbabyburn
oh please, don't compare python docs to php docs, php docs show one function
per page, because their api is WRONG, python shows them often per module
level, how to compose the api of a module and use them with actual examples,
the doc is useful for experienced developers.

I feel this article is advertising their book, maybe the only point to
consider is the somewhat broken status of pip that have to deals with system
libraries dependencies, but whatever, I still use pip every day and with
multiple production deploys.

Is there some good comment about python docs, packaging management, that isn't
so much a rant?

~~~
vacri
This being said, I find the PHP docs' styling to be easier to read. The python
docs are all over the place.

This being said, the PHP doc linked to in the article is 15% document, and 85%
user comments (why do docs even have user comments?). Yuck.

~~~
iaskwhy
While I understand the idea of not having user comments, back when I was doing
php - and remember this was a time without StackOverflow - checking the docs
user comments would get me going very quickly as some particular use cases
would always show up there (and with improvements from other users too).

------
gamesbrainiac
I'd suggest using ZealDocs or Dash if you want fast searchable documentation.

------
oscii
Regarding libraries, I often check unit tests for examples. But yeah, regex
and similar docs suck.

------
Chris2048
I'd like details on the "installing libraries" comment. for python, most
distros come with a package, otherwise compilation is rarer.

If compiling python, or even something like opencv that requires compilation
on any random linux distro - yes, you need to be able to figure it out. linux
distros aren't all standardised.

~~~
the_mitsuhiko
> I'd like details on the "installing libraries" comment. for python, most
> distros come with a package, otherwise compilation is rarer.

Installing python modules from a system's package manager is not something
people should do. It causes more issues than it solves.

~~~
majewsky
Can you go into more detail? So far, for my basic scripting needs, system
packages have always been fine.

~~~
ubernostrum
First of all, distro packages essentially always lag behind the released
upstream versions, so you have to begin with figuring out which version the
distro packaged, and find documentation for that, include that version in all
your questions to the mailing list for the library, and hope that you're not
on a version so old that it's no longer supported upstream.

Then there's the way distros like to make changes for "consistency" with the
rest of their system. Command-line entry points get renamed or have options
and behavior changed to reflect the distro's standards, but now the thing
you're running isn't the thing upstream wrote or documented, so you're even
more on your own if you hit trouble.

Also, it's not unheard-of for distros to take something that's a single
packaged entity upstream, and split it into multiple distro packages, possibly
without making it entirely clear that to get full functionality you'll have to
install multiple distro packages. And, again, this is specific to the distro
and their choices, so of course upstream won't document it and may be just as
baffled as you are when you ask why something that's important to you doesn't
seem to be in the package you got.

Finally, the Python ecosystem is built around the _Python_ packaging and
distribution toolchains. You're going to find plenty of expertise in things
like using pip and virtual environments to develop and deploy Python, but all
that goes out the window when you switch to using the distro package manager
and packages. So you're giving up a lot of tooling built by and for Python
engineers, for something which had to be a one-size-fits-all solution for the
operating system it's bound to.

So while you can do all right with system packages and tooling for quite a few
use cases, the dangers aren't that far away and are ready to hurt you, badly,
as soon as you stray just a little bit outside of what the distro optimized
for, or need help with a package beyond what the distro and its packagers are
able to provide.

~~~
majewsky
Hm okay, at least the first two things don't apply for me since Arch Linux
updates usually within a few days, and likes to stay as close to upstream as
possible.

------
Cozumel
Maybe instead of trying to teach others with a 'book project' he should try
teaching himself and learn the actual language then he wouldn't have these
kind of imaginary 'issues'!!

------
gaur
Has anyone made tldr pages for python packages?

