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

[Stephan Richter]

On Monday 27 September 2004 01:47, Peter Mayne wrote:
> > First of all, factories are often not just the class. In fact, they
> > commonly are not the class. Often they are a function that puts a
> > security proxy around the object, once it is created. See the
> > 'zope:content' directive handler to see what I am talking about.
>
> Fair enough, but I've read nothing about this in the book so far. (I
> haven't read it all, so I may very well have missed something.) The book
> offers createObject() as a way of creating objects, with no obvious
> alternatives, and no real explanation of how to use it: no docstring,
> looking at the source isn't very helpful, 

There is no alternative to createObject() and as I stated in my previous 
reply, this is quiet important. 

> and how do I create a factory in the first place?

Usually factories are created using ZCML. Therefore the book does not explain 
the manual CA way of doing it. And of course it is documented, like all API 
functions. See zope.component.interfaces.

A factory has to provide the IFactory interface and is registered as a utility 
providing IFactory. The name of the utility is the name you pass to 
createObject().

> And then it turns out I don't need it after all, 
> which turns out to be much simpler. :-)

You do not need it in all cases, but often you do need it.

> So, when *do* I need a factory?

You automatically use factories when dealing with ZCML-registered content 
components. You need them when creating an object involves more than just 
instantiating a class.

> Why do I need a security proxy around an object?

Because you do not want everyone to have access to all attributes of an 
object.

> Why doesn't such a seemingly important method as createObject() 
> have any docstring at all?

Because documentation is always kept in the interfaces.

> >>Having now just created a new object, I've tried to rename it:
> >>
> >>         msg = self.context['msg1']
> >>         del self.context['msg1']
> >>         self.context['msg2'] = msg
> >>
> >>which didn't work.
> >
> > Mmmh, this should have worked, since it calls all the necessary code.
>
> I was getting a "no such attribute as '__parent__'" error or somesuch.
> After playing with a different problem which ended up at the same error,
> I ended up subclassing my implementation from
> zope.app.container.contained.Contained, which I suspect would solve this
> problem as well.

Right, I forgot about that. Since your context is a Zope 3 application server 
based container, your contained objects must provide IContained, so that we 
can walk up and down the object tree without hassle.

> > Right. I do not think programming-based copy and move are such common
> > operations that it is worth mentioning in the book.
>
> On the contrary, it's because they are common operations that it's all
> the more important that they should be mentioned. Where else am I going
> to find out about them? Really.

I am in doubt. I have been using Zope since 1999 and I have seldomly (if ever) 
written manual copy and paste code.

> >>Even sadder, rename() doesn't even have a
> >>docstring. (Yes, I know it's obvious in this case, but its the principle
> >>of the thing. :-)
> >
> > The documentation of rename is really in the ObjectMover class. But
> > please feel free to add some documentation to the rename() function
> > itself for clarity.
>
> It's not in the class docstring. And how am I supposed to know that
> there is an ObjectMover class that has a rename() method? Is it
> mentioned in any documentation?

You can look at the rename() implementation and see that it is really just a 
convenience function that uses ObjectMover. So if you want to understand 
rename(), you must understand ObjectMover, therefore the hint to look there. 
However, I do agree this function needs a docstring.

> However, things below the level of the framework such as creating, managing, 
> and deleting objects don't get mentioned.

This is because you usually create and manage objects via the Management 
interface. Look at the bugtracker's XML import code on how to at least 
manually create objects.

> Arguably, this kind of stuff should come with the Z3 distribution.
> On the other hand, I'm a developer, and I'm reading a 
> developer's handbook, and (certainly in my case) it's a reasonable
> assumption that I'm ignorant of Z3. Even after reading the book, I don't
> see how I could write bugtracker's bug importer, because I still
> wouldn't know how to create my own IBug objects.

I decided to skip the XML import/export chapter for the book, since I did not 
want to make it too long. My assumption is that once you read all of the 
book, you are familiar enough with the framework, that you can do such tasks.

> How about a chapter called "Zope 3 API" which goes through some of the
> basic non-framework subjects?

What would it be about?

> How do I manipulate objects?

Aehm, I think most of the chapters in part C & D cover various aspects of 
manipulation.

> What the heck is IContained for? ... 

I am pretty sure I explain IContained in chapter 7. 

> Excellent, but where is it documented? Again, the book is about the Z3
> framework, not management of a Z3 instance, so I wouldn't necessarily
> expect to find out about packing Data.fs in there, but it would be nice
> to find such things somewhere. I presume the documentation exists
> somewhere, but I just haven't found it yet.

For the 3.0 release we have not concentrated on the user and administrator 
experience much at all. Therefore there are very few management tools at this 
point. Therefore there is also no documentation for the few existing tools, 
since major restructuring seems to be coming.

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