Ticket #5174: ticket-5174-2-docs.patch

File ticket-5174-2-docs.patch, 5.4 KB (added by wirehead, 4 years ago)

v2 patch, fixed a few more things.

  • twisted/python/components.py

     
    190190
    191191
    192192class Componentized:
    193     """I am a mixin to allow you to be adapted in various ways persistently.
     193    """
     194    Componentized is a mixin to allow you to be adapted in various ways
     195    persistently.
    194196
    195     I define a list of persistent adapters.  This is to allow adapter classes
    196     to store system-specific state, and initialized on demand.  The
    197     getComponent method implements this.  You must also register adapters for
    198     this class for the interfaces that you wish to pass to getComponent.
     197    Componentized define a list of persistent adapters.  This is to allow
     198    adapter classes to store system-specific state, and initialized on demand.
     199    The getComponent method implements this.  You must also register adapters
     200    for this class for the interfaces that you wish to pass to getComponent.
    199201
    200202    Many other classes and utilities listed here are present in Zope3; this one
    201203    is specific to Twisted.
     
    207209        self._adapterCache = {}
    208210
    209211    def locateAdapterClass(self, klass, interfaceClass, default):
     212        """
     213        Return registered adapter for a given class and interface.
     214
     215        Note that is tied to the *Twisted* global registry, and will
     216        thus not find adapters registered elsewhere.
     217
     218        @param klass: The adapter class
     219
     220        @param interfaceClass: the interface class.
     221
     222        #param default: The default adapter to return.
     223        """
    210224        return getAdapterFactory(klass, interfaceClass, default)
    211225
    212226    def setAdapter(self, interfaceClass, adapterClass):
    213227        """
    214228        Cache a provider for the given interface, by adapting C{self} using
    215229        the given adapter class.
     230
     231        @param interfaceClass: the interface class.
     232
     233        #param adapterClass: the adapter class to register
    216234        """
    217235        self.setComponent(interfaceClass, adapterClass(self))
    218236
    219237    def addAdapter(self, adapterClass, ignoreClass=0):
    220         """Utility method that calls addComponent.  I take an adapter class and
    221         instantiate it with myself as the first argument.
     238        """Utility method that calls addComponent.
    222239
     240        @param adapterClass: The component to be instantiated with
     241        the current object as the first argument. 
     242
     243        @param ignoreClass: In order to determine which interfaces are
     244        appropriate, the component's provided interfaces will be scanned.
     245        If the argument 'ignoreClass' is True, then all interfaces are
     246        considered appropriate.
     247
    223248        @return: The adapter instantiated.
    224249        """
    225250        adapt = adapterClass(self)
     
    229254    def setComponent(self, interfaceClass, component):
    230255        """
    231256        Cache a provider of the given interface.
     257
     258        @param interfaceClass: The interface class the component
     259        is an adapter for.
     260
     261        @param component: The component to be added.
    232262        """
    233263        self._adapterCache[reflect.qual(interfaceClass)] = component
    234264
    235265    def addComponent(self, component, ignoreClass=0):
    236266        """
    237         Add a component to me, for all appropriate interfaces.
     267        Add a component, for all appropriate interfaces.
    238268
    239         In order to determine which interfaces are appropriate, the component's
    240         provided interfaces will be scanned.
     269        @param component: The component to be added.
    241270
     271        @param ignoreClass: In order to determine which interfaces are
     272        appropriate, the component's provided interfaces will be scanned.
    242273        If the argument 'ignoreClass' is True, then all interfaces are
    243274        considered appropriate.
    244275
    245276        Otherwise, an 'appropriate' interface is one for which its class has
    246277        been registered as an adapter for my class according to the rules of
    247278        getComponent.
    248 
    249         @return: the list of appropriate interfaces
    250279        """
    251280        for iface in declarations.providedBy(component):
    252281            if (ignoreClass or
     
    255284                self._adapterCache[reflect.qual(iface)] = component
    256285
    257286    def unsetComponent(self, interfaceClass):
    258         """Remove my component specified by the given interface class."""
     287        """
     288        Remove the component specified by the given interface class.
     289
     290        @param interfaceClass: The interface class to be removed.
     291        """
    259292        del self._adapterCache[reflect.qual(interfaceClass)]
    260293
    261294    def removeComponent(self, component):
    262295        """
    263         Remove the given component from me entirely, for all interfaces for which
     296        Remove the given component entirely, for all interfaces for which
    264297        it has been registered.
    265298
     299        @param component: The component to be removed.
     300
    266301        @return: a list of the interfaces that were removed.
    267302        """
    268303        l = []
     
    287322        If you want to automatically register an adapter for all appropriate
    288323        interfaces (with addComponent), set the attribute 'multiComponent' to
    289324        True on your adapter class.
     325
     326        @param interface: The interface to be added
     327
     328        @param default: The default adapter to return if there isn't one
     329        already present.
     330
     331        @return: default or an adapter for the interface.
    290332        """
    291333        k = reflect.qual(interface)
    292334        if k in self._adapterCache: