Re: Questions about API documentation
selphi...@gmail.com writes: > I am trying to understand how to write good API documentation. I have read > “7. Documenting Python” in the python developers guide [1] and skimmed the > Doc-SIG email archives, but I still have some questions and I would > appreciate your help. (Whenever I refer to me in the following questions, I > mean documentation authors in general) I fear that has much to do with preference -- both on the side of the author as on the side of the user. Personally, I prefer documentation of the following kind: * an overview document gives the grand picture (architecture, primary concepts, building blocks) * detail documentation is terse - based mainly on well chosen names with some additional information where this is necessary * if necessary, e.g. for a specific target audience, an additional document give usage/configuration examples > 1) How much should I (or a documentation author in general) go into detail? I > don’t want to bore experienced users, but I don’t want to scare beginners > away either. You go into details where a typical user would get at a loss without the detail. What is "typical" depends on your target audience. It is more an experienced user when the target audience is "senior developer" (e.g. for a module like "ctypes"); it is more a beginner when the target audience is "occasional developer". > 2) Should I give a code example for each method and object? Only, if it is non trivial -- or in a separate document/part of the documentation targeted at less experienced users. > 3) I recognize 2 different kinds of examples: Some are rather small and right > under the object or method description and some are quite long and at the end > of a module in a use case. Which kind is encouraged at which conditions? My preferences would say: the first kind is likely unnecessary altogether. The second kind may be good in non obvious cases. > 4) The documentation of the Python Standard Library is quite verbose or like > a book / tutorial. Some other documentations like JavaDoc [2] or PerlDoc [3] > use a more reference-like documentation. Why did Python choose a different > approach? Was this discussed before? The Python library documentation is rather heterogenous in this respect -- likely because many different people with different preferences have contributed. > 5) Do you have any other advice? Are there things I should be aware of? I should say that there is a big camp with completely different preferences from mine. I mean the "doctest" camp. It favours to combine documentation and testing and advices to have executable docstrings covering all test cases. This gives a very detailed documentation. As you can imagine I do not like this advice and the resulting documentation at all. From my point of view, the requirements for good documentation (overview, compactness, concept based) are quite different from those for testing (completeness) and for me such documentation is difficult to read. -- https://mail.python.org/mailman/listinfo/python-list
Re: Better way to do this dict comprehesion
Sayth Renshaw wrote: > Hi > > I have got this dictionary comprehension and it works but how can I do it > better? List comprehensions (that's what you have) are nice, but overused. > from collections import Counter > > def find_it(seq): > counts = dict(Counter(seq)) There is no need to convert Counter to dict. > a = [(k, v) for k,v in counts.items() if v % 3 == 0] > return a[0][0] > > test_seq = [20,1,-1,2,-2,3,3,5,5,1,2,4,20,4,-1,-2,5] > > so this returns 5 which is great and the point of the problem I was doing. > > Can also do it like this > def find_it(seq): > counts = dict(Counter(seq)) > a = [(k) for k,v in counts.items() if v % 3 == 0] > return a[0] > > But the given problem states there will always only be one number > appearing an odd number of times given that is there a neater way to get > the answer? If you mean there is only one number satisfying the v % 3 == 0 condition then there is no need to go through the whole sequence. The clearest way to express that is for k, v in counts.items(): if v % 3 == 0: return k raise ValueError but it = (k for k, v in counts.items() if v % 3 == 0) try: return next(it) except StopIteration: pass raise ValueError is also possible. The parens (...) instead of [...] make "it" generator expression which is evaluated lazily. Both alternatives shown above ensure that at least one value satisfies the condition "number of occurencies divides by three without rest". If you want to play it safe and verify that there is exactly one such key you may keep the listcomp, preferably that from your second implementation. a = [...] if len(a) != 1: raise ValueError return a[0] or [result] = a # will raise a ValueError if len(a) != 1 The complete code: >>> from collections import Counter >>> def find_it(seq): ... [result] = [k for k, v in Counter(seq).items() if v % 3 == 0] ... return result ... >>> test_seq = [20,1,-1,2,-2,3,3,5,5,1,2,4,20,4,-1,-2,5] >>> find_it(test_seq) 5 -- https://mail.python.org/mailman/listinfo/python-list
Alternative to signals in threads
I've been unsuccessfully looking for an alternative for signals, that works in
threads.
After updating a script of mine from being single-threaded to being
multi-threaded, I realised that signals do not work in threads.
I've used signals to handle blocking operations that possibly take forever like:
signal.signal(signal.SIGALRM, wait_timeout)
# wait_timeout simply does: raise Exception("timeout")
signal.setitimer(signal.ITIMER_REAL,5)
# So a timer of 5 seconds start and I run my operation
try:
p = Popen(["tool", "--param"], stdin=PIPE, stdout=PIPE, stderr=STDOUT)
for line in p.stdout:
if "STRING" in str(line):
signal.setitimer(signal.ITIMER_REAL,0)
p.terminate()
print("Success")
except:
p.terminate()
print("Timeout")
Now this works great with a single thread, but doesn't work at all with
multiple threads.
A more throughout example can be found here:
https://gist.github.com/saatomic/841ddf9c5142a7c75b03daececa8eb17
What can I use instead of signals in this case?
Thanks and kind regards,
SaAtomic
--
https://mail.python.org/mailman/listinfo/python-list
Run Python in iPad/iPhone
Analyser is the only iOS app that integrated both Python and R engines. build-in popular Python modules for stats/machine learning/image processing: numpy,scipy,matplotlib,scikit-learn,scikit-image,pandas,pymc,nilearn,astroML,statsmodels,astropy.. https://itunes.apple.com/cn/app/fen-xi-zhe/id1083042861?mt=8 If you just want get a testing version, pls let me know the email address of your Apple ID. -- https://mail.python.org/mailman/listinfo/python-list
Re: Better way to do this dict comprehesion
Peter I really like this The complete code: >>> from collections import Counter >>> def find_it(seq): ... [result] = [k for k, v in Counter(seq).items() if v % 3 == 0] ... return result ... >>> test_seq = [20,1,-1,2,-2,3,3,5,5,1,2,4,20,4,-1,-2,5] >>> find_it(test_seq) But what may be the smallest thing in this i had no idea I could do [result] = blah and get a generator on the return variable that seems insane. Cheers Sayth -- https://mail.python.org/mailman/listinfo/python-list
Re: Better way to do this dict comprehesion
Sayth Renshaw wrote:
> Peter I really like this
>
> The complete code:
>
from collections import Counter
def find_it(seq):
> ... [result] = [k for k, v in Counter(seq).items() if v % 3 == 0]
> ... return result
> ...
test_seq = [20,1,-1,2,-2,3,3,5,5,1,2,4,20,4,-1,-2,5]
find_it(test_seq)
>
> But what may be the smallest thing in this i had no idea I could do
> [result] = blah and get a generator on the return variable that seems
> insane.
Usually this is done with tuples
>>> left, sep, right = "foo.bar".partition(".") # looks familiar?
rather than the alternative spelling
>>> [left, sep, right] = "foo.bar".partition(".")
However, a 1-tuple is just a trailing comma and easy to overlook, so i
prefer
>>> items = [42]
>>> [foo] = items
>>> foo
42
over
>>> bar, = items
>>> bar
42
--
https://mail.python.org/mailman/listinfo/python-list
Re: Better way to do this dict comprehesion
Sayth Renshaw writes: > Peter I really like this > > The complete code: > from collections import Counter def find_it(seq): > ... [result] = [k for k, v in Counter(seq).items() if v % 3 == 0] > ... return result You confirmed to Chris that you want the item that occurs an odd number of times. The test for that is v % 2 == 1. Or just v % 2, given that 0 and 1 are considered false and true, resp. But v % 3 == 0 is something else. -- https://mail.python.org/mailman/listinfo/python-list
Re: Better way to do this dict comprehesion
Sayth Renshaw writes:
>> To find an unpaired number in linear time with minimal space, try
>> stepping through the list and either adding to a set or removing from
>> it. At the end, your set should contain exactly one element. I'll let
>> you write the actual code :)
>>
>> ChrisA
>
> ChrisA the way it sounds through the list is like filter with map and
> a lambda. http://www.python-course.eu/lambda.php Haven't had a good go
> yet... will see how it goes.
You mean reduce(xor, map(lambda o : {o}. With suitable imports.
I think Chris is suggesting the same thing but in the piecemeal way of
updating a set at each element. You can test for membership, o in res,
and then res.add(o) or res.remove(o) depending on the test.
And you need to say set() to make an empty set, because {} is dict().
Your input sequence is guaranteed non-empty, but it's simply easier to
start with an empty res.
--
https://mail.python.org/mailman/listinfo/python-list
What's the neatest way of getting dictionary entries in a specified order?
I have a fairly simple application that populates a GUI window with
fields from a database table. The fields are defined/configured by a
dictionary as follows:-
#
#
# Address Book field details, dictionary key is the database column
#
dbcol = {}
dbcol['firstname'] = col('First Name', True, False)
dbcol['lastname'] = col('Last Name', True, False)
dbcol['email'] = col('E-Mail', True, True)
dbcol['phone'] = col('Phone', True, True)
dbcol['mobile'] = col('Mobile', True, True)
dbcol['address'] = col('Address', True, False)
dbcol['town'] = col('Town/City', True, False)
dbcol['county'] = col('County/Region', True, False)
dbcol['postcode'] = col('PostCode', True, False)
dbcol['country'] = col('Country', True, False)
dbcol['notes'] = col('Notes', True, False)
dbcol['www'] = col('Web Page', True, True)
dbcol['categories'] = col('Categories', True, True)
How can I get the fields in the GUI window in the order I want rather
than the fairly random order that they appear in at the moment?
Currently the GUI fields are populated by a for loop as follows:-
#
#
# Put values into the fields
#
i = 0
for col, field in abookdb.dbcol.items():
print(field.heading)
if (i > numkeys/2):
self.addfieldentry(col, address, field, self.rtable, i-numkeys/2)
else:
self.addfieldentry(col, address, field, self.ltable, i)
i = i + 1
The for loop gets the items from the dictionary in an order that isn't
what I want. How can I configure things so they're in the order I want?
--
Chris Green
·
--
https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
On 03/08/2017 11:27 AM, Chris Green wrote: The for loop gets the items from the dictionary in an order that isn't what I want. How can I configure things so they're in the order I want? What order do you want? -- ~Ethan~ -- https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
Chris Green writes:
> I have a fairly simple application that populates a GUI window with
> fields from a database table. The fields are defined/configured by a
> dictionary as follows:-
>
> #
> #
> # Address Book field details, dictionary key is the database column
> #
> dbcol = {}
> dbcol['firstname'] = col('First Name', True, False)
> dbcol['lastname'] = col('Last Name', True, False)
> dbcol['email'] = col('E-Mail', True, True)
> dbcol['phone'] = col('Phone', True, True)
> dbcol['mobile'] = col('Mobile', True, True)
> dbcol['address'] = col('Address', True, False)
> dbcol['town'] = col('Town/City', True, False)
> dbcol['county'] = col('County/Region', True, False)
> dbcol['postcode'] = col('PostCode', True, False)
> dbcol['country'] = col('Country', True, False)
> dbcol['notes'] = col('Notes', True, False)
> dbcol['www'] = col('Web Page', True, True)
> dbcol['categories'] = col('Categories', True, True)
>
> How can I get the fields in the GUI window in the order I want rather
> than the fairly random order that they appear in at the moment?
Look up OrderedDict in the collections module.
--
https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
Ethan Furman wrote: > On 03/08/2017 11:27 AM, Chris Green wrote: > > > The for loop gets the items from the dictionary in an order that isn't > > what I want. How can I configure things so they're in the order I want? > > What order do you want? > Well probably the First Name and Last Name, then phone or E-Mail. But it hardly matters, I just want to be able to specify the order. -- Chris Green · -- https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
Jussi Piitulainen wrote:
> Chris Green writes:
>
> > I have a fairly simple application that populates a GUI window with
> > fields from a database table. The fields are defined/configured by a
> > dictionary as follows:-
> >
> > #
> > #
> > # Address Book field details, dictionary key is the database column
> > #
> > dbcol = {}
> > dbcol['firstname'] = col('First Name', True, False)
> > dbcol['lastname'] = col('Last Name', True, False)
> > dbcol['email'] = col('E-Mail', True, True)
> > dbcol['phone'] = col('Phone', True, True)
> > dbcol['mobile'] = col('Mobile', True, True)
> > dbcol['address'] = col('Address', True, False)
> > dbcol['town'] = col('Town/City', True, False)
> > dbcol['county'] = col('County/Region', True, False)
> > dbcol['postcode'] = col('PostCode', True, False)
> > dbcol['country'] = col('Country', True, False)
> > dbcol['notes'] = col('Notes', True, False)
> > dbcol['www'] = col('Web Page', True, True)
> > dbcol['categories'] = col('Categories', True, True)
> >
> > How can I get the fields in the GUI window in the order I want rather
> > than the fairly random order that they appear in at the moment?
>
> Look up OrderedDict in the collections module.
Thanks, that's what I need.
--
Chris Green
·
--
https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
On Thursday, March 9, 2017 at 1:03:31 AM UTC+5:30, Chris Green wrote:
> I have a fairly simple application that populates a GUI window with
> fields from a database table. The fields are defined/configured by a
> dictionary as follows:-
>
> #
> #
> # Address Book field details, dictionary key is the database column
> #
> dbcol = {}
> dbcol['firstname'] = col('First Name', True, False)
> dbcol['lastname'] = col('Last Name', True, False)
> dbcol['email'] = col('E-Mail', True, True)
> dbcol['phone'] = col('Phone', True, True)
> dbcol['mobile'] = col('Mobile', True, True)
> dbcol['address'] = col('Address', True, False)
> dbcol['town'] = col('Town/City', True, False)
> dbcol['county'] = col('County/Region', True, False)
> dbcol['postcode'] = col('PostCode', True, False)
> dbcol['country'] = col('Country', True, False)
> dbcol['notes'] = col('Notes', True, False)
> dbcol['www'] = col('Web Page', True, True)
> dbcol['categories'] = col('Categories', True, True)
>
> How can I get the fields in the GUI window in the order I want rather
> than the fairly random order that they appear in at the moment?
>
> Currently the GUI fields are populated by a for loop as follows:-
>
> #
> #
> # Put values into the fields
> #
> i = 0
> for col, field in abookdb.dbcol.items():
> print(field.heading)
> if (i > numkeys/2):
> self.addfieldentry(col, address, field, self.rtable, i-numkeys/2)
> else:
> self.addfieldentry(col, address, field, self.ltable, i)
> i = i + 1
>
> The for loop gets the items from the dictionary in an order that isn't
> what I want. How can I configure things so they're in the order I want?
>
> --
> Chris Green
> ·
There is OrderedDict.
https://docs.python.org/2/library/collections.html#collections.OrderedDict
https://docs.python.org/3/library/collections.html#collections.OrderedDict
--
https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
On Thu, Mar 9, 2017 at 6:27 AM, Chris Green wrote:
> dbcol['firstname'] = col('First Name', True, False)
> dbcol['lastname'] = col('Last Name', True, False)
http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/
ChrisA
--
https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
Chris Angelico wrote:
> On Thu, Mar 9, 2017 at 6:27 AM, Chris Green wrote:
> > dbcol['firstname'] = col('First Name', True, False)
> > dbcol['lastname'] = col('Last Name', True, False)
>
> http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/
>
Yes, I'm well aware of these issues, but it's my personal address book
so I can avoid many/most of them.
--
Chris Green
·
--
https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
On Thu, Mar 9, 2017 at 8:25 AM, Chris Green wrote:
> Chris Angelico wrote:
>> On Thu, Mar 9, 2017 at 6:27 AM, Chris Green wrote:
>> > dbcol['firstname'] = col('First Name', True, False)
>> > dbcol['lastname'] = col('Last Name', True, False)
>>
>> http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/
>>
> Yes, I'm well aware of these issues, but it's my personal address book
> so I can avoid many/most of them.
So you assume that you'll never meet someone from another culture?
Okay. I'm pretty sure that counts as bigoted, but sure :)
As a general rule, it's safest to just have a single "name" field and
have done with it.
ChrisA
--
https://mail.python.org/mailman/listinfo/python-list
Re: Alternative to signals in threads
Use multiprocessing since you want to do multiple things at once https://pymotw.com/2/multiprocessing/basics.html If I understand you correctly, once the string is found you would terminate the process, so you would have to signal the calling portion of the code using a Manager dictionary or list.. I am not that knowledgeable about multiprocessing, so this is probably the long way around the barn. import time from multiprocessing import Process, Manager def test_f(test_d): ctr=0 while True: ctr += 1 print "test_f", test_d["QUIT"], ctr time.sleep(1.0) if ctr > 5: test_d["QUIT"]=True if __name__ == '__main__': ## define the dictionary to be used to communicate manager = Manager() test_d = manager.dict() test_d["QUIT"] = False ## start the process p = Process(target=test_f, args=(test_d,)) p.start() ## check the dictionary every half-second while not test_d["QUIT"]: time.sleep(0.5) p.terminate() -- https://mail.python.org/mailman/listinfo/python-list
Re: What's the neatest way of getting dictionary entries in a specified order?
On 03/08/2017 12:27 PM, Chris Green wrote: > I have a fairly simple application that populates a GUI window with > fields from a database table. The fields are defined/configured by a > dictionary as follows:- Instead of ordering the data in Python, why not rely on the GUI to do the sort? Most GUI's even have table widgets that let you click on the headings to sort arbitrarily. -- https://mail.python.org/mailman/listinfo/python-list
