Re: [Tutor] Prescriptive vs descriptive docstring
On 11/05/12 04:41, Kal Sze wrote: PEP 257 says that docstrings should be written in a prescriptive way (i.e. using the imperative mood) instead of a descriptive way (indicative mood). This seems like a rather odd recommendation. Since the docstring is supposed to tell the programmer *how* to use a function/method, This might be down to interpretation of the terms. To me it means the docstring should tell, or instruct, the user how to use the function. It should not describe what the function does or how it does it (the internal logic). command? Who are you "commanding" when what you really want is to learn what the function/method does? It's commanding (or instructing) the user on how to use the function. You don't need to know what its doing internally, only how to use it. It tells me that if I push these things in, it will give me that thing back. But that's just how I interpret it. Somebody else may have a more definitive explanation. -- Alan G Author of the Learn to Program web site http://www.alan-g.me.uk/ ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
[Tutor] pip errors for numpy, scipy matplotlib
Hi, when attempting to use pip to install numpy, scipy matplotlib I get a mile of errors. There is simply too much information printed - so it must be a systematic error (http://paste.ubuntu.com/982180/). What am I missing/doing wrong? Kind Regards, Bjorn ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] pip errors for numpy, scipy matplotlib
On Fri, May 11, 2012 at 2:42 PM, Bjorn Madsen wrote: > Hi, > when attempting to use pip to install numpy, scipy matplotlib I get a mile > of errors. There is simply too much information printed - so it must be a > systematic error (http://paste.ubuntu.com/982180/). What am I missing/doing > wrong? The error messages sound like you're missing a bunch of the thing required to build the packages you're trying to compile. It looks like libraries called Atlas and Blas, plus a fortran compiler, from the errors you posted. Are you using ubuntu? You didn't say, but I see you're using a ubuntu pastebin. Are you wedded to compiling and installing with pip? It's a whole lot easier to just use the packaging system included with ubuntu when you can. In this case you should be able to do `sudo apt-get install python-numpy` to install numpy. If you do want to compile and build via pip, I would start by doing `sudo apt-get build-dep python-numpy` to get all the required prerequisites installed, then retry installing via pip. -- Jerry ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] Prescriptive vs descriptive docstring
Kal Sze wrote: Hello, PEP 257 says that docstrings should be written in a prescriptive way (i.e. using the imperative mood) instead of a descriptive way (indicative mood). PEP 257: http://www.python.org/dev/peps/pep-0257/ For those who don't know English grammatical terms, here are some examples. Imperative mood: - "Return the number of widgets in a set." - "Control access to the phlebotinum." - "Set the printer on fire." Indicative mood: - "[This function] returns the number of widgets in a set." - "[This class] controls access to the phlebotinum." - "[This method] sets the printer on fire." This seems like a rather odd recommendation. Since the docstring is supposed to tell the programmer *how* to use a function/method, I've always thought that a description in the indicative mood is appropriate. What's the point in saying it like a command? Who are you "commanding" when what you really want is to learn what the function/method does? "You" is the person writing the doc string, that is, the person writing the code (or someone working on her behalf). So the imperative mood is commanding the computer: "Method, you will set the printer on fire." If I had to guess a reason why this convention exists, it would be that some people don't like implying the subject of the imperative mood, or think it is ungrammatical to say "Sets the printer on fire" without stating who or what sets the printer on fire. But it gets tiresome very, very quickly to preface every doc string with "This function...", "This method..." etc. But as I said, that's a guess. In Javadoc and XML doc (Java's and .NET's equivalent to docstrings), the de-facto convention is to use the indicative mood (as can be seen in the whole standard java class library and .net class library). Is this difference somehow a corollary of the difference in programming paradigms? I doubt it. I suspect it was just somebody's personal preference. Personally, I don't pay too much attention to PEP 257. Some attention, but I don't follow it slavishly. And neither does the standard library -- for example, the decimal module has a mix of imperative and indicative mood in the doc strings. In any case, unless you are writing for the Python standard library, nobody can force you to follow PEP 257. It may be *recommended*, but you are free to ignore it, and take the consequences. Was there a discussion in doc-...@python.org about the reason(s) to use the imperative mood instead of the indicative mood, which then led to the recommendation in PEP 257? You would be better off asking on doc-sig@ or python-...@python.org. -- Steven ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] Sorting the Parts of a Dictionary into a List
Jacob Bender wrote: The total function works when it returns the strength of a neuron, but I don't think the "sorted" function is the best because, with its current configuration, it returns a type error. I have been doing python for several years now. I don't know EVERYTHING there is to know, but I am able to do most tasks without error. Please help me get the neurons into an order in a list as described in my original email. Also, I do thank you for your original replies! Jacob, please read this article, for some excellent advice about asking for help: http://sscce.org/ This will help us to help you. -- Steven ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
