On Sun, Jul 31, 2011 at 1:38 AM, Barry Warsaw wrote:
> On Jul 31, 2011, at 01:23 AM, Nick Coghlan wrote:
>
>>It sounds to me like you're really objecting to the devguide living in
>>a separate clone. This doesn't bode well for the prospects of ever
>>splitting the stdlib out from the CPython inter
On Jul 31, 2011, at 01:23 AM, Nick Coghlan wrote:
>It sounds to me like you're really objecting to the devguide living in
>a separate clone. This doesn't bode well for the prospects of ever
>splitting the stdlib out from the CPython interpreter core...
Actually, no. I'm objecting to moving docum
On Sat, Jul 30, 2011 at 1:49 AM, Barry Warsaw wrote:
> On Jul 30, 2011, at 01:02 AM, Nick Coghlan wrote:
> If test.support is truly and only an internal implementation detail, then it
> should adhere to Pythonic convention for such things, and be renamed
> test._support. Then you won't need to do
On Sat, 30 Jul 2011 09:25:27 -0400
Terry Reedy wrote:
> >
> > I'm sorry, can you be more precise. The effect of what?
>
> Your proposal to remove the current formatted documentation of
> test.support instead of completing it and force all developers to only
> have reference to the docstrings sc
On 7/29/2011 7:27 PM, Antoine Pitrou wrote:
On Fri, 29 Jul 2011 19:02:32 -0400
Terry Reedy wrote:
On 7/29/2011 5:32 PM, Antoine Pitrou wrote:
On Fri, 29 Jul 2011 11:51:18 -0400
Barry Warsaw wrote:
The solution then is to rename test.support to test._support to make it clear
it's an intern
On 7/29/2011 6:54 PM, Antoine Pitrou wrote:
On Fri, 29 Jul 2011 18:47:07 -0400
Terry Reedy wrote:
And test.support *is* for internal use.
No, the stuff in there is *not* for internal use within the module but
for external use is possiby every test module.
I meant internal use for us. Real
Am 27.07.2011 19:47, schrieb Terry Reedy:
> On 7/27/2011 1:27 PM, Brett Cannon wrote:
>
>> Perhaps what we could do is move the documentation for test.support to
>> the devguide, and then vet the test suite so that unlink and friends
>> are always called as 'support.unlink', etc.
>>
>>
Am 27.07.2011 19:44, schrieb Terry Reedy:
> On 7/27/2011 9:24 AM, Antoine Pitrou wrote:
>
>> Docstrings are sufficient for own our purposes.
>
> >>> import test.support as t
> >>> help(t.rmtree)
> Help on function rmtree in module test.support:
>
> rmtree(path)
Well, what are you waiting for.
Am 29.07.2011 11:26, schrieb Barry Warsaw:
> So I'm curious, why is this move better than adding noindexes, or just
> trusting users to understand the difference between test.support.unlink() and
> os.unlink()? If I currently search for 'unlink', os.unlink comes up first,
> which is good, and tha
On Fri, 29 Jul 2011 23:32:57 +0200, Antoine Pitrou wrote:
> On Fri, 29 Jul 2011 11:51:18 -0400
> Barry Warsaw wrote:
> > On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote:
> >
> > >> test.support *is* part of the stdlib.
> > >
> > >We have lots of internal APIs which are not documented, though.
On Fri, 29 Jul 2011 19:02:32 -0400
Terry Reedy wrote:
> On 7/29/2011 5:32 PM, Antoine Pitrou wrote:
> > On Fri, 29 Jul 2011 11:51:18 -0400
> > Barry Warsaw wrote:
> >> On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote:
> >>
> test.support *is* part of the stdlib.
> >>>
> >>> We have lots of
On 7/29/2011 5:32 PM, Antoine Pitrou wrote:
On Fri, 29 Jul 2011 11:51:18 -0400
Barry Warsaw wrote:
On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote:
test.support *is* part of the stdlib.
We have lots of internal APIs which are not documented, though.
And test.support *is* for internal use
On Fri, 29 Jul 2011 18:47:07 -0400
Terry Reedy wrote:
>
> > And test.support *is* for internal use.
>
> No, the stuff in there is *not* for internal use within the module but
> for external use is possiby every test module.
I meant internal use for us. Really, whether or not it's
used cross-mo
On 7/29/2011 11:25 AM, Antoine Pitrou wrote:
t
We have lots of internal APIs which are not documented, though.
They are generally used only within the module itself as helper
functions. So one only needs to even know about them when looking at the
module code.
And test.support *is* for int
On 7/29/2011 11:18 AM, Barry Warsaw wrote:
I'd much rather solve this problem by adding markup to functions that
explicitly disclaim our normal backward compatibility guarantees.
I suggested adding a footnote marker (1) to each one.
test.support *is* part of the stdlib.
So once again, is
On Fri, 29 Jul 2011 11:51:18 -0400
Barry Warsaw wrote:
> On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote:
>
> >> test.support *is* part of the stdlib.
> >
> >We have lots of internal APIs which are not documented, though.
> >And test.support *is* for internal use.
>
> The solution then is to
On Fri, 29 Jul 2011 11:49:01 -0400, Barry Warsaw wrote:
> If test.support is truly and only an internal implementation detail, then it
> should adhere to Pythonic convention for such things, and be renamed
> test._support. Then you won't need to document it at all except in the
> module.
I'd be
On Jul 29, 2011, at 12:13 PM, R. David Murray wrote:
>In that case, you are working *on Python*. Not using Python.
My point was, it's a fine line between the two.
>Personally, I always thought the devguide should be part of Docs anyway.
>It isn't because people didn't want it versioned along si
On Fri, 29 Jul 2011 11:18:37 -0400, Barry Warsaw wrote:
> On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote:
> >Isn't this what we're trying to prevent, though? One should never even have
> >to look at test.support unless he's working *on Python*.
>
> Again, I think that line is blurred here. Le
On Jul 29, 2011, at 05:25 PM, Antoine Pitrou wrote:
>> test.support *is* part of the stdlib.
>
>We have lots of internal APIs which are not documented, though.
>And test.support *is* for internal use.
The solution then is to rename test.support to test._support to make it clear
it's an internal i
On Jul 30, 2011, at 01:02 AM, Nick Coghlan wrote:
>It's worthwhile because it is what the devguide is for: documenting
>how to *change* Python, rather than just using it as it is delivered
>to you. There's a clear transition from user of Python to developer of
>Python: you stop treating the standa
On 7/29/2011 8:18 AM, Barry Warsaw wrote:
I think the devguide should document things like
...
"how to ensure code works
across all existing interpreter implementations", "where to find continuous
integration results and how to interpret them"
...
I don't think the devguide should document
On Sat, Jul 30, 2011 at 1:32 AM, Nick Coghlan wrote:
> So the documentation on how
> to *run* the test suite belongs in the devguide, but the details of
> how the test suite works internally, including the APIs that are used
> to write new tests, belong in the dev guide.
Gah, that first instance
On Sat, Jul 30, 2011 at 1:18 AM, Barry Warsaw wrote:
> On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote:
>>I think the unlink&rmtree functions are just a symptom. The real issue here
>>is - what is the devguide for, and how is it different from Python's
>>existing documentation? What should go in
Barry Warsaw wrote:
On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote:
I think the unlink&rmtree functions are just a symptom. The real issue here
is - what is the devguide for, and how is it different from Python's
existing documentation? What should go into the official docs, and what
should g
On Fri, 29 Jul 2011 11:18:37 -0400
Barry Warsaw wrote:
>
> I'd much rather solve this problem by adding markup to functions that
> explicitly disclaim our normal backward compatibility guarantees. Squirreling
> away documentation for some parts of the stdlib seems similar to
> security-by-obscur
On Jul 29, 2011, at 02:07 PM, Eli Bendersky wrote:
>Why is it part of stdlib though? Isn't the stdlib something that's exposed
>to all Python programmers? How should an ordinary programmer (not a core
>dev) know some parts of stdlib are out of limits, if they are even
>documented and appear in the
On Fri, Jul 29, 2011 at 7:26 PM, Barry Warsaw wrote:
> The devguide, as useful and cool as it is, is still immature and hard to
> discover. I think more time will improve its organization, and it's not even
> linked to from docs.python.org.
>
> So I'm curious, why is this move better than adding
> >Alright, I think there's now a sufficiently wide consensus to move the
> >documentation of Lib/test and Lib/test/support in particular to the
> >devguide, which raises a question:
>
> I haven't been following this thread, so I caught up on Gmane.
>
> I'm somewhat uncomfortable with this decision
On Jul 29, 2011, at 08:24 AM, Eli Bendersky wrote:
>Alright, I think there's now a sufficiently wide consensus to move the
>documentation of Lib/test and Lib/test/support in particular to the
>devguide, which raises a question:
I haven't been following this thread, so I caught up on Gmane.
I'm s
On Fri, Jul 29, 2011 at 4:52 PM, Eli Bendersky wrote:
> On Fri, Jul 29, 2011 at 08:48, Nick Coghlan wrote:
>>
>> On Fri, Jul 29, 2011 at 3:24 PM, Eli Bendersky wrote:
>> > I propose to just move 3K's docs to the devguide, and make both doc
>> > pages
>> > (in 3K and 2.7) point to it. Is this acc
On Fri, Jul 29, 2011 at 08:48, Nick Coghlan wrote:
> On Fri, Jul 29, 2011 at 3:24 PM, Eli Bendersky wrote:
> > I propose to just move 3K's docs to the devguide, and make both doc pages
> > (in 3K and 2.7) point to it. Is this acceptable?
>
> Yeah, just include a note in the devguide version sayi
On Fri, Jul 29, 2011 at 3:24 PM, Eli Bendersky wrote:
> I propose to just move 3K's docs to the devguide, and make both doc pages
> (in 3K and 2.7) point to it. Is this acceptable?
Yeah, just include a note in the devguide version saying that anything
added in 3.2 or later may not be available wh
On Fri, Jul 29, 2011 at 03:39, Nick Coghlan wrote:
> On Fri, Jul 29, 2011 at 7:33 AM, Brett Cannon wrote:
> >> However, is there any reason why test.support itself shouldn't be
> renamed
> >> test._support, or possibly _test.support, so that the *entire* suite is
> >> marked as a private impleme
On Fri, Jul 29, 2011 at 7:33 AM, Brett Cannon wrote:
>> However, is there any reason why test.support itself shouldn't be renamed
>> test._support, or possibly _test.support, so that the *entire* suite is
>> marked as a private implementation detail?
>
> Technically no for the _test idea, although
On Wed, Jul 27, 2011 at 16:53, Steven D'Aprano wrote:
> Eli Bendersky wrote:
>
> Sure, but I'm still leery of two functions with the same name doing acting
>> slightly differently.
>>
>
>
> and then in a later post:
>
>
> As I mentioned elsewhere, it's not good practice to have two functions
>>
On Thu, Jul 28, 2011 at 02:53, Steven D'Aprano wrote:
> Eli Bendersky wrote:
>
> Sure, but I'm still leery of two functions with the same name doing acting
>> slightly differently.
>>
>
>
> and then in a later post:
>
>
> As I mentioned elsewhere, it's not good practice to have two functions
>>
Eli Bendersky wrote:
Sure, but I'm still leery of two functions with the same name doing acting
slightly differently.
and then in a later post:
As I mentioned elsewhere, it's not good practice to have two functions with
the same name doing something slightly different, in different modules
On Thu, Jul 28, 2011 at 3:27 AM, Brett Cannon wrote:
> On Wed, Jul 27, 2011 at 06:36, R. David Murray
> wrote:
>> Perhaps what we could do is move the documentation for test.support to
>> the devguide, and then vet the test suite so that unlink and friends
>> are always called as 'support.unlink'
On Wed, 27 Jul 2011 10:27:16 -0700
Brett Cannon wrote:
> >
> > Perhaps what we could do is move the documentation for test.support to
> > the devguide, and then vet the test suite so that unlink and friends
> > are always called as 'support.unlink', etc.
> >
>
> I like this solution since this is
Eli Bendersky wrote:
I like this solution since this issue of documenting
test.support keeps
coming up. Otherwise we can not document test.support,
We already do.
25.6. test.support — Utility functions for tests
is about half of the page that also contains
On 7/27/2011 1:57 PM, Eli Bendersky wrote:
Out of curiosity, why would a user need to run Python's tests?
If one compiles Python, running the tests is essential.
Some people like to run a test suite to verify an installation.
Sometimes people have problems that might arise from an installation
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1
On 07/27/2011 01:57 PM, Eli Bendersky wrote:
> Out of curiosity, why would a user need to run Python's tests?
A couple of cases occur to me:
- - To verify that they got a corrrect build with all expected modules
included.
- - To test the build af
> I like this solution since this issue of documenting test.support keeps
>> coming up. Otherwise we can not document test.support,
>>
>
> We already do.
>
> 25.6. test.support — Utility functions for tests
> is about half of the page that also contains
> 25.5. test — Regression tests package for P
On 7/27/2011 1:27 PM, Brett Cannon wrote:
Perhaps what we could do is move the documentation for test.support to
the devguide, and then vet the test suite so that unlink and friends
are always called as 'support.unlink', etc.
I like this solution since this issue of documenting tes
On 7/27/2011 9:24 AM, Antoine Pitrou wrote:
Docstrings are sufficient for own our purposes.
>>> import test.support as t
>>> help(t.rmtree)
Help on function rmtree in module test.support:
rmtree(path)
;-)
--
Terry Jan Reedy
___
Python-Dev mailing
> ---
> Side note: test.support.import_fresh_**module typo. /is/if/ in
> "This function will raise unittest.SkipTest is the named module cannot be
> imported."
>
Fixed in 8989aa5b357c
Eli
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.pyt
> Ezio, this is also a good idea, but currently I really think placing
>> this documentation in the devguide is probably the best approach. Now we
>> have a very nice Devguide, and this documentation simply belongs there,
>> and not in the user-visible portion of the official Python documentation.
On Wed, Jul 27, 2011 at 06:36, R. David Murray wrote:
> On Wed, 27 Jul 2011 16:14:40 +0300, Eli Bendersky
> wrote:
> > 1. In the documentation of test.support mention explicitly that it's code
> > for CPython's internal use only, and these APIs aren't guaranteed to be
> > stable.
>
> This was alr
On 7/27/2011 10:27 AM, Eli Bendersky wrote:
Initially I was *for* documenting, but this thing with showing up
in the index is a compelling counter-point.
"The basic version makes entries in the general index; if no index
entry is desired, you can give the directive option flag
On 7/27/2011 9:24 AM, Antoine Pitrou wrote:
On Wed, 27 Jul 2011 16:14:40 +0300
Eli Bendersky wrote:
Will it take long for newbie code to appear with the test.support version?
Not to mention that grepping code that imports the "unlink" function
directly doesn't reveal which one is being used.
On Wed, 27 Jul 2011 16:58:53 +0300, Eli Bendersky wrote:
> R. David Murray wrote:
> > But they aren't redundant, since the test.support versions ignore
> > errors.
>
> As I mentioned elsewhere, it's not good practice to have two functions with
> the same name doing something slightly different, i
> Initially I was *for* documenting, but this thing with showing up in the
> index is a compelling counter-point.
>
>
> "The basic version makes entries in the general index; if no index entry is
> desired, you can give the directive option flag :noindex:." (
> http://docs.python.org/documenting/m
Hi,
On 27/07/2011 16.35, Eli Bendersky wrote:
> 1. In the documentation of test.support mention
explicitly that it's code
> for CPython's internal use only, and these APIs
aren't
> > 2. Some functions like unlink and rmtree are obviously redundant, and
> shadow
> > frequently used Python stdlib functions, so I would either kill them
> > completely or at least rename them appropriately.
>
> But they aren't redundant, since the test.support versions ignore
> errors.
>
As I m
On Wed, 27 Jul 2011 16:14:40 +0300, Eli Bendersky wrote:
> 1. In the documentation of test.support mention explicitly that it's code
> for CPython's internal use only, and these APIs aren't guaranteed to be
> stable.
This was already done.
> 2. Some functions like unlink and rmtree are obviously
> > 1. In the documentation of test.support mention explicitly that it's code
> > for CPython's internal use only, and these APIs aren't guaranteed to be
> > stable.
>
> There is a top-level note at
> http://docs.python.org/dev/library/test.html, but it won't be visible
> by people who arrive at an
On Wed, 27 Jul 2011 16:14:40 +0300
Eli Bendersky wrote:
>
> Will it take long for newbie code to appear with the test.support version?
> Not to mention that grepping code that imports the "unlink" function
> directly doesn't reveal which one is being used.
>
> I think this is troublesome. I thin
>
>
>
> The mere fact that these functions exist in a different module suggests
> different semantics from those found in other places in the stdlib. I don't
> think they should be renamed simply because some code imports the functions
> directly instead of the module itself (suggesting they should
On Sat, Jul 23, 2011 at 20:35, Eli Bendersky wrote:
> Some background: I'm working (on and off) on issue 11015 - documenting
> the public functions in test.support
>
> Some of the functions in test.support (for example unlink, rmtree)
> simply shadow existing & popular stdlib functions, with the
Some background: I'm working (on and off) on issue 11015 - documenting
the public functions in test.support
Some of the functions in test.support (for example unlink, rmtree)
simply shadow existing & popular stdlib functions, with the aim of
swallowing the exceptions these may throw. This is confu
61 matches
Mail list logo
