[Zope3-dev] Re: Creating new objects in a package

[Stephan Richter]

On Monday 27 September 2004 20:27, Peter Mayne wrote:
> The book says (p53): "Factories, as the name suggests, exist merely to
> create other components and objects." There's no mention in that section
> of why I should use a factory when I could just create an object myself.
> It's possible that such information is scattered around the rest of the
> book, but it would be good to have it in one place.

Okay, I'll add some more explanation there.

> Rhetorical (for now) question: when/why does creating an object involve
> more than just instantiating a class?

Because you need to give the framework a chance to do some other things too, 
like securing the object.

> I don't know Z3, so I really don't 
> know what else is involved. There seems to be an assumption that I
> already know this, possibly because I'm supposed to be coming to Z3 from
> Z2, but that's not the case.

No, I think the less Zope 2 experience you have, the better off you are.

> By reading the relevant parts of the book, I managed to write all of my
> XML importer except for the part where I actually create the objects,
> which is what led to this thread. I still can't see how I could have
> figured out something so fundamental by reading the book. I think that's
> a pretty glaring omission.

I just thought of the chapter that demonstrates adding objects manually, and 
it does not even use factories. <grin> The XML-RPC chapter shows you how to 
create a message using Python. In this case I did not need the factory, since 
I do not care about security. Note that I still have to create the 
ObjectCreatedEvent for the object, so that subscribers to this event have a 
chance to do their work as well. This is really important. The workflow 
manager listens to this event and adds the workflow to the message, once it 
is created.

Here is another great advantage of factories. Factories are Python path 
independent. For example, if you use a the MessageBoard in your application 
and you use the class directly, then you are screwed, if I move the package 
to another location in the Python path and you will have to correct your 
import. If you use the factory instead, you have to make no changes to the 
code, since the factory id will not change.

> How do I create objects?

Okay, so that's in the XML-RPC chapter.

> Factories vs simple Python object creation; when/why would I use one or the 
> other. 

I am going to add some explanation to the spot where I mention factories.

> How do I traverse the database?

That's a ZODB issue. At first I wanted to document the ZODB a bit too, but 
eventually decided against it, since it is a huge task and worth another 
small book. There is plenty ZODB documentation out there.

If you talk about the Zope 3 application traversal framework, I agree I 
neglected this a bit. But it would be a couple sentences only, since 
traversal is usually done for you by the publisher. What a developer is 
usually interested in is how to hook into the traversal process, which I 
describe in "Changing Traversal Behavior". The short answer to this question 
is to read the API documentation 
zope.app.traversing.interfaces.ITraversalAPI.

> How do I find things in the database?

What do you mean by "find"?

> How can I do these things from a 
> command line/script, so I don't have to click through a bunch of web
> pages to try things out? 

I provided you a way in the book using XML-RPC and FTP. Low-level Python 
inspection of the ZODB is left for ZODB to document.

> Glimpses of the API. 

I believe I cover the most common API calls and features for an application 
developer. There are bits and pieces that I do not cover, but I hate books 
with a thousand pages. 

> >>What the heck is IContained for? ...
> >
> > I am pretty sure I explain IContained in chapter 7.
>
> There is one mention of IContained in the book, in section 28.3: "Since
> the principal source is stored inside an authentication service, we need
> to make it a IContained object." That doesn't really tell me much.

Not true, though I meant to write chapter 13.
http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/Zope3Book/contentobject.html

> However, documentation is severely lacking, so it looks like yet another 
> uphill battle. 

How much more do you expect? We have

- a detailed and up-to-date tutorial in the forms of slides and notes,

- a book that tells you how to develop Zope 3 content-based applications and 
reveals many other tricks,

- another book being written by Phillip,

- several README.txt files in the packages themselves,

- a good API documentation (note that all documentation is in the interfaces), 
which can be accessed from any running Zope 3 using 
http://localhost:8080/++apidoc++,

- and many online resources, like the proposals, guidelines and so on, 
including the mailing list.

There are not many software projects out there that have that much 
documentation, let alone before the first full release.

You have to realize that there are only 40-50 Zope 3 developers of which are 
usually only 2-5 are active at any given time.

> Don't get me wrong: so far, the book is great. It concentrates on the
> framework, but that leaves out a lot of stuff. The few tutorials I've
> found also concentrate on the framework. This leaves huge gaps which I
> have to navigate through.

Of course, nothing is very complete at this point. It will take some exposure 
of the software to see what people really need to know. While writing the 
book I have asked people numerous times of what they think is missing from 
the book and have commonly added chapters based on their recommendation. I am 
hesitant to do so now, since the book has been delivered to the publisher 
already. However, I am open to suggestions for the 3.1 edition.

> That means I have to ask more questions. :-) 

No problem, as long as you document the answers and your experience in one 
form or another publically, for example in a small how-to.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training