Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder1.news.weretis.net!feeder.erje.net!eu.feeder.erje.net!newsfeed.freenet.ag!news2.euro.net!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.006 X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'subject:Python': 0.05; 'defaults': 0.05; 'imply': 0.09; 'issue?': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'terry': 0.09; 'yeah,': 0.09; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'reedy': 0.16; 'sure.': 0.16; 'wrote:': 0.17; 'issue,': 0.17; 'jan': 0.18; 'bit': 0.21; 'raise': 0.24; 'idea': 0.24; 'header:In- Reply-To:1': 0.25; 'header:User-Agent:1': 0.26; 'entries': 0.27; 'header:X-Complaints-To:1': 0.28; 'assert': 0.29; 'methods.': 0.29; 'strings,': 0.29; 'actively': 0.30; 'basic': 0.30; 'checked': 0.30; 'url:python': 0.32; 'int': 0.33; 'to:addr:python- list': 0.33; 'text': 0.34; 'along': 0.35; 'acceptable': 0.35; 'built-in': 0.35; 'massive': 0.35; 'open': 0.35; 'pm,': 0.35; 'subject:?': 0.35; "won't": 0.35; 'there': 0.35; 'received:org': 0.36; 'url:org': 0.36; 'method': 0.36; 'should': 0.36; 'itself': 0.37; 'does': 0.37; 'rather': 0.37; 'subject:: ': 0.38; 'url:docs': 0.38; 'to:addr:python.org': 0.39; 'header:Received:5': 0.40; 'kind': 0.61; 'helping': 0.63; 'more': 0.63; 'special': 0.73; 'received:fios.verizon.net': 0.84; 'top.': 0.84; 'url:datamodel': 0.84; 'url:reference': 0.84; 'subject:you': 0.88 X-Injected-Via-Gmane: http://gmane.org/ To: python-list@python.org From: Terry Reedy Subject: Re: Do you feel bad because of the Python docs? Date: Tue, 26 Feb 2013 20:48:51 -0500 References: <512cb0a0$0$30001$c3e8da3$5496439d@news.astraweb.com> <57fd0b09-b30d-4e62-845a-aac198113a40@googlegroups.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Gmane-NNTP-Posting-Host: pool-173-75-251-66.phlapa.fios.verizon.net User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:17.0) Gecko/20130215 Thunderbird/17.0.3 In-Reply-To: X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 26 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1361929752 news.xs4all.nl 6856 [2001:888:2000:d::a6]:47045 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:40021 On 2/26/2013 1:52 PM, Devin Jeanpierre wrote: > I would assert it isn't very kind to those even with basic fundamentals. > > For example, under precisely what circumstances does int() raise > TypeError? You won't find that under either int's documentation, or > TypeError's documentation, you have to look it up under __int__, which > is _not_ a basic fundamental. And rather than helping you along the > way, the documentation for int() actively misleads you by its > implicature that the only acceptable types are strings, ints, and > floats. And then even if you have the foresight to remember "oh yeah, > isn't there a special method for this?", you have to find the > documentation for __int__, which is itself is three quarters of the > way down this massive page: > http://docs.python.org/2/reference/datamodel.html Have you opened an issue, or checked for existing issue? I would be open to the idea that entries like that for int should not be overly type specific and imply that the defaults are the only possibilities. Perhaps there should be a cross-reference to corresponding special methods. Perhaps that idea might be opposed. I am not sure. Perhaps Built-in Functions needs a bit more general explanatory text at the top. -- Terry Jan Reedy