From: Stefan S. <se...@sy...> - 2006-04-09 19:13:24
|
I just tried to use publish_from_doctree(), which as per its doc-string suggests that it returns a pair of encoded output as well as document parts. It appears it actually only returns the encoded output. I'm using version 0.4release. Thanks, Stefan |
From: David G. <go...@py...> - 2006-04-09 19:52:21
Attachments:
signature.asc
|
[Stefan Seefeld] > I just tried to use publish_from_doctree(), which as per its > doc-string suggests that it returns a pair of encoded output > as well as document parts. It appears it actually only returns > the encoded output. > I'm using version 0.4release. True. The docstring gives the intended interface, but it would break cod= e to change the API now. Is this significant? We could add a "parts" paramet= er to allow client code to choose the return type: just string output or an (ou= tput, parts) tuple. Thoughts? CC-ing Martin Blais & Felix Wiemann to get their opinions. --=20 David Goodger <http://python.net/~goodger> |
From: Stefan S. <se...@sy...> - 2006-04-09 19:58:34
|
David Goodger wrote: > [Stefan Seefeld] >> I just tried to use publish_from_doctree(), which as per its >> doc-string suggests that it returns a pair of encoded output >> as well as document parts. It appears it actually only returns >> the encoded output. >> I'm using version 0.4release. > > True. The docstring gives the intended interface, but it would break code to > change the API now. Is this significant? We could add a "parts" parameter to > allow client code to choose the return type: just string output or an (output, > parts) tuple. Thoughts? I'm not sure about the API itself, but the doc-string should surely reflect the API, not what it would look like if backwards compatibility wasn't an issue. ;-) Thanks, Stefan |
From: David G. <go...@py...> - 2006-04-09 20:13:49
Attachments:
signature.asc
|
[Stefan Seefeld] > I'm not sure about the API itself, but the doc-string should surely ref= lect > the API, not what it would look like if backwards compatibility wasn't > an issue. ;-) Of course the docstring should be fixed to match the API, whatever we dec= ide. That goes without saying. In this case, the docstring documents the inte= nded API, but for whatever reason the code doesn't implement it. It's a bug; = I'm just not sure whether to take backward compatibility into account when fi= xing it, or not. --=20 David Goodger <http://python.net/~goodger> |
From: Beni C. <cb...@us...> - 2006-04-12 13:28:27
|
T24gNC85LzA2LCBEYXZpZCBHb29kZ2VyIDxnb29kZ2VyQHB5dGhvbi5vcmc+IHdyb3RlOgo+IEl0 J3MgYSBidWc7IEknbSBqdXN0IG5vdCBzdXJlIHdoZXRoZXIgdG8gdGFrZSBiYWNrd2FyZCBjb21w YXRpYmlsaXR5Cj4gaW50byBhY2NvdW50IHdoZW4gZml4aW5nIGl0LCBvciBub3QuCj4KSWYgYW55 Ym9keSB1c2VzIHRoaXMgZnVuY3Rpb24gdG9kYXkgYW5kIGlzIGNvbnRlbnQgd2l0aCBqdXN0IGEg c3RyaW5nIG91dHB1dCDigJQKaXQncyBhIHVzZSBjYXNlIGZvciB0aGUgY3VycmVudCBBUEkgdGhh dCB3b24ndCBiZWNvbWUgYmV0dGVyIGlmIHlvdSBjaGFuZ2UgdGhlCmZ1bmN0aW9uIHRvIHJldHVy biBhIHBhaXIuICBTbyBJIHRoaW5rIHlvdSBzaG91bGQga2VlcCB0aGlzIGZ1bmN0aW9uCmFzIGEg Y29udmVuaWVuY2UKZnVuY3Rpb24gcmV0dXJuaW5nIGp1c3QgYSBzdHJpbmcgKGZpeCB0aGUgZG9j KSwgYW5kIGFkZCBhIG5ldyBmdW5jdGlvbgpyZXR1cm5pbmcgYSBwYWlyLgoKQnV0IGlmIHRoZSBm dW5jdGlvbiB3aWxsIHJldHVybiBhIGAoc3RyaW5nLCBwYXJ0cylgIHBhaXIsIHdvbid0CmBzdHJp bmdgIGFsd2F5cyBlcXVhbApgcGFydHNbJ3dob2xlJ11gPyAgSWYgc28sIEkgZG9uJ3Qgc2VlIGFu eSBiZW5lZml0IHRvIHRoZSBwYWlyIGludGVyZmFjZSBhdCBhbGwuCgotLQpCZW5pIENoZXJuaWF2 c2t5IDxjYmVuQHVzZXJzLnNmLm5ldD4sIHdobyBjYW4gb25seSByZWFkIGVtYWlsIG9uIHdlZWtl bmRzLgpHb3Zlcm5tZW50cyBhcmUgbGlrZSBrZXJuZWxzIC0gZXZlcnl0aGluZyBwb3NzaWJsZSBz aG91bGQgYmUgZG9uZSBpbiB1c2VyIHNwYWNlLgo= |
From: Stefan S. <se...@sy...> - 2006-04-12 13:32:50
|
Beni Cherniavsky wrote: > But if the function will return a `(string, parts)` pair, won't > `string` always equal > `parts['whole']`? If so, I don't see any benefit to the pair interface at all. I fully agree, FWIW. Regards, Stefan |
From: Stefan S. <se...@sy...> - 2006-04-12 13:40:31
|
Actually, what I find a bit surprising about the publish_<> API is that it is flexible in the output type, and - with publish_from_doctree being the exception - uses the same way to specify the input. What if I want a 'publish_parts_from_doctree' ? Could there be a way to fold the 'from doctree' input type into the other publish functions ? That would make the various output types accessible to those who want to operate on an existing doctree. Thanks, Stefan |
From: David G. <go...@py...> - 2006-04-12 14:42:13
Attachments:
parts-from-doctree-session.txt
|
On 4/12/06, Stefan Seefeld <se...@sy...> wrote: > Actually, what I find a bit surprising about the publish_<> API > is that it is flexible in the output type, and - with publish_from_doctre= e > being the exception - uses the same way to specify the input. These are convenience functions. They are all simply wrappers around the Publisher object, that set up the system in certain well-known ways for convenient use. The existing functions allow for the vast majority of use cases, but they are not meant to provide every possible way to set up and run a Docutils sytem. They are not meant to provide an orthogonal, comprehensive API. It's impossible to provide ultimate convenience to every user. There is a publish_programmatically function that provides for all the parameters, and returns the Publisher object for further access (i.e., get at whatever you want, including the Publisher.parts attribute). If what you need can't be done through publish_programmatically, you can roll your own. The publish_* convenience functions provide plenty of examples of how to do it properly. > What if I want a 'publish_parts_from_doctree' ? That was the reason for intending to return both the output and the parts dictionary from publish_from_doctree. There seem to be two users of this function: you and Martin Blais. If you both agree, I'll be happy to make the function conform to the docstring. I don't want to make the change without agreement, because it would certainly break code. > Could there be a way > to fold the 'from doctree' input type into the other publish functions ? Of course there is, and it's possible right now. See the attached session. But we're not going to add some kind of "give me the parts as output" parameter, because that would complicate the API. > That would make the various output types accessible to those who want > to operate on an existing doctree. I don't think that's a big enough use case to be worth worrying about. If you disagree, please prepare a patch. -- David Goodger <http://python.net/~goodger> |
From: Stefan S. <se...@sy...> - 2006-04-12 14:47:04
|
David Goodger wrote: >> What if I want a 'publish_parts_from_doctree' ? > > That was the reason for intending to return both the output and the > parts dictionary from publish_from_doctree. There seem to be two users > of this function: you and Martin Blais. If you both agree, I'll be > happy to make the function conform to the docstring. I don't want to > make the change without agreement, because it would certainly break > code. Ok, since you asked: I'd be happy for this function to return the parts dictionary only, since (IIUC) the full output would be accessible as parts['whole']. Martin, do you agree ? Thanks, Stefan |
From: David G. <go...@py...> - 2006-04-12 14:45:04
|
On 4/12/06, Beni Cherniavsky <cb...@us...> wrote: > On 4/9/06, David Goodger <go...@py...> wrote: > > It's a bug; I'm just not sure whether to take backward compatibility > > into account when fixing it, or not. > > If anybody uses this function today and is content with just a string out= put =97 > it's a use case for the current API that won't become better if you chang= e the > function to return a pair. So I think you should keep this function > as a convenience > function returning just a string (fix the doc), That's probably what we'll do. > and add a new function returning a pair. But I don't think we need to do that. > But if the function will return a `(string, parts)` pair, won't > `string` always equal > `parts['whole']`? If so, I don't see any benefit to the pair interface a= t all. Not quite. parts['whole'] is a Unicode string, and the string output is encoded (i.e. ready for writing to a binary file). -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2006-06-06 02:21:29
|
Stefan Seefeld wrote: > I just tried to use publish_from_doctree(), which as per its > doc-string suggests that it returns a pair of encoded output as well > as document parts. It appears it actually only returns the encoded > output. I fixed the docstring. I gotta say I'm not entirely content with the current approach of having a bunch of only half-orthogonal functions. We could partly avoid the compatibility by using an interface such as this: facade = docutils.Facade(version=1) facade.publish_... Then we can make changes to the Facade interface and bump the version to 2, keeping compatibility if the Facade is instantiated with version=1. But I'm not really convinced if this is a good idea. I'm still waiting for enlightenment... -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |