diff --git a/doc/core/howto/application.xhtml b/doc/core/howto/application.xhtml index 79f19db..3b6601a 100644 --- a/doc/core/howto/application.xhtml +++ b/doc/core/howto/application.xhtml @@ -95,37 +95,40 @@ Client service.

twistd and tac

-

To handle start-up and configuration of your Twisted application, the -Twisted Application infrastructure uses .tac files. -.tac are Python files which configure an Application object and assign this -object to the top-level variable application.

+

To handle start-up and configuration of your Twisted application, +the Twisted Application infrastructure uses .tac +files. .tac are Python files which configure +an Application object and +assign this object to the top-level +variable application.

The following is a simple example of a .tac file:

service.tac -

twistd is a program that runs Twisted applications using a -.tac file. In its most simple form, it takes a single argument --y and a tac file name. For example, you can run the above server -with the command twistd -y service.tac.

+

twistd is a program that runs Twisted applications +using a .tac file. In its most simple form, it takes a +single argument -y and a tac file name. For example, you +can run the above server with the command twistd +-y service.tac.

-

By default, twistd daemonizes and logs to a file called -twistd.log. More usually, when debugging, you will want your -application to run in the foreground and log to the command line. To run the -above file like this, use the command twistd -noy -service.tac

+

By default, twistd daemonizes and logs to a file +called twistd.log. More usually, when debugging, you will +want your application to run in the foreground and log to the command +line. To run the above file like this, use the +command twistd -noy service.tac

For more information, see the twistd man page.

Customizing twistd logging in a .tac application

-The logging behavior can be customized through an API -accessible from .tac files. The ILogObserver component can be -set on an Application in order to customize the default log observer that -twistd will use. +The logging behavior can be customized through an API accessible +from .tac files. The ILogObserver component can be set on +an Application in order to customize the default log observer +that twistd will use.

@@ -146,7 +149,7 @@ application.setComponent(ILogObserver, FileLogObserver(logfile).emit)

invoking twistd -y my.tac will create a log file -at/tmp/my.log. +at /tmp/my.log.

Services provided by Twisted

@@ -253,11 +256,13 @@ corresponds to reactor.connectTCP.

Service Collection

IServiceCollection objects contain -IService objects. -IService objects can be added to IServiceCollection by calling setServiceParent and detached -by using IServiceCollection objects +contain IService objects. IService +objects can be added to IServiceCollection by +calling setServiceParent +and detached by using disownServiceParent.

The standard implementation of IServiceCollection is Application -

Twisted programs usually work with -twisted.application.service.Application. -This class usually holds all persistent configuration of -a running server -- ports to bind to, places where connections -to must be kept or attempted, periodic actions to do and almost -everything else. It is the root object in a tree of services implementing -IService.

+

Twisted programs usually work +with twisted.application.service.Application. +This class usually holds all persistent configuration of a running +server -- ports to bind to, places where connections to must be kept +or attempted, periodic actions to do and almost everything else. It is +the root object in a tree of services implementing IService.

Other HOWTOs describe how to write custom code for Applications, but this one describes how to use already written code (which can be @@ -52,10 +52,11 @@ directory. When a straight Python file which defines an Application object called application is used, use the -y option.

-

When twistd runs, it records its process id in a -twistd.pid file (this can be configured via a command line -switch). In order to shutdown the twistd process, kill that -pid (usually you would do kill `cat twistd.pid`). +

When twistd runs, it records its process +id in a twistd.pid file (this can be configured via a +command line switch). In order to shutdown +the twistd process, kill that pid (usually +you would do kill `cat twistd.pid`).

As always, the gory details are in the manual page.

@@ -63,25 +64,26 @@ pid (usually you would do kill `cat twistd.pid`).

OS Integration

-If you have an Application that runs with twistd, -you can easily deploy it on RedHat Linux or Debian GNU/Linux based systems -using the tap2deb or tap2rpm tools. These take a Twisted Application file (of -any of the supported formats — Python source, XML or pickle), and build a -Debian or RPM package (respectively) that installs the Application as a system -service. The package includes the Application file, a default -/etc/init.d/ script that starts and stops the process with twistd, -and post-installation scripts that configure the Application to be run in the -appropriate init levels. +If you have an Application that runs +with twistd, you can easily deploy it on +RedHat Linux or Debian GNU/Linux based systems using +the tap2deb +or tap2rpm tools. These take a Twisted +Application file (of any of the supported formats — Python source, XML +or pickle), and build a Debian or RPM package (respectively) that +installs the Application as a system service. The package includes the +Application file, a default /etc/init.d/ script that +starts and stops the process with twistd, and post-installation +scripts that configure the Application to be run in the appropriate +init levels.

-
-tap2rpm and tap2deb do -not package your entire application and dependent code, just the Twisted -Application file. You will need to find some other way to package your Python -code, such as distutils' bdist_rpm -command. +
tap2rpm +and tap2deb do not package your entire +application and dependent code, just the Twisted Application file. You +will need to find some other way to package your Python code, such +as distutils' bdist_rpm command.

diff --git a/doc/core/howto/components.xhtml b/doc/core/howto/components.xhtml index 3567d6e..135e4ef 100644 --- a/doc/core/howto/components.xhtml +++ b/doc/core/howto/components.xhtml @@ -8,18 +8,21 @@

Components: Interfaces and Adapters

-

Object oriented programming languages allow programmers to reuse portions of -existing code by creating new classes of objects which subclass another -class. When a class subclasses another, it is said to inherit all of its -behaviour. The subclass can then override and extend the behavior -provided to it by the superclass. Inheritance is very useful in many situations, -but because it is so convenient to use, often becomes abused in large software -systems, especially when multiple inheritance is involved. One solution is to -use delegation instead of inheritance where appropriate. -Delegation is simply the act of asking another object to perform a task -for an object. To support this design pattern, which is often referred to as the -components pattern because it involves many small interacting components, -interfaces and adapters were created by the Zope 3 team.

+

Object oriented programming languages allow programmers to reuse +portions of existing code by creating new classes of objects +which subclass another class. When a class subclasses another, it is +said to inherit all of its behaviour. The subclass can +then override and extend the behavior provided to it by +the superclass. Inheritance is very useful in many situations, but +because it is so convenient to use, often becomes abused in large +software systems, especially when multiple inheritance is +involved. One solution is to use delegation instead +of inheritance where appropriate. Delegation is simply the act +of asking another object to perform a task for an object. To +support this design pattern, which is often referred to as +the components pattern because it involves many small +interacting components, interfaces and adapters were +created by the Zope 3 team.

Interfaces are simply markers which objects can use to say I implement this interface. Other objects may then make requests like @@ -100,16 +103,18 @@ technique called composition, which relies on delegation rather than inheritance to break code into small reusable chunks. Let us continue with the Multiple Inheritance example, though, because it is often used in practice.

-

What if both the Color and the Area base class defined the same method, -perhaps calculate? Where would the implementation come from? The -implementation that is located for Square().calculate() depends on -the method resolution order, or MRO, and can change when programmers change -seemingly unrelated things by refactoring classes in other parts of the system, -causing obscure bugs. Our first thought might be to change the calculate method -name to avoid name clashes, to perhaps calculateArea and -calculateColor. While explicit, this change could potentially -require a large number of changes throughout a system, and is error-prone, -especially when attempting to integrate two systems which you didn't write.

+

What if both the Color and the Area base class defined the same +method, perhaps calculate? Where would the implementation +come from? The implementation that is located +for Square().calculate() depends on the method resolution +order, or MRO, and can change when programmers change seemingly +unrelated things by refactoring classes in other parts of the system, +causing obscure bugs. Our first thought might be to change the +calculate method name to avoid name clashes, to +perhaps calculateArea and calculateColor. +While explicit, this change could potentially require a large number +of changes throughout a system, and is error-prone, especially when +attempting to integrate two systems which you didn't write.

Let's imagine another example. We have an electric appliance, say a hair dryer. The hair dryer is american voltage. We have two electric sockets, one of @@ -151,11 +156,12 @@ I was plugged in improperly and now you have no hair dryer any more. -

We are going to attempt to solve this problem by writing an Adapter for the -ForeignSocket which converts the voltage for use with an American -hair dryer. An Adapter is a class which is constructed with one and only one -argument, the adaptee or original object. In this example, we -will show all code involved for clarity:

+

We are going to attempt to solve this problem by writing an Adapter +for the ForeignSocket which converts the voltage for use +with an American hair dryer. An Adapter is a class which is +constructed with one and only one argument, the adaptee +or original object. In this example, we will show all code +involved for clarity:

 class AdaptToAmericanSocket:
@@ -213,13 +219,14 @@ the class block do not have any method body! Since Python does not have any
 native language-level support for Interfaces like Java does, this is what
 distinguishes an Interface definition from a Class.

 
-
Now that we have a defined Interface, we can talk about objects using terms
-like this: The AmericanSocket class implements the
-IAmericanSocket interface and Please give me an object which
+
Now that we have a defined Interface, we can talk about objects
+using terms like this: The AmericanSocket class
+implements the IAmericanSocket interface
+and Please give me an object which
 adapts ForeignSocket to the IAmericanSocket
-interface. We can make declarations about what interfaces a certain
-class implements, and we can request adapters which implement a certain
-interface for a specific class.

+interface. We can make declarations about what interfaces
+a certain class implements, and we can request adapters which
+implement a certain interface for a specific class.

 
 
Let's look at how we declare that a class implements an interface:

 
@@ -234,12 +241,13 @@ class AmericanSocket:
         return 110
-

So, to declare that a class implements an interface, we simply call -zope.interface.implements at the class level.

+

So, to declare that a class implements an interface, we simply +call zope.interface.implements at the class level.

-

Now, let's say we want to rewrite the AdaptToAmericanSocket -class as a real adapter. In this case we also specify it as implementing -IAmericanSocket:

+

Now, let's say we want to rewrite +the AdaptToAmericanSocket class as a real adapter. In +this case we also specify it as +implementing IAmericanSocket:

 from zope.interface import implements
@@ -258,15 +266,17 @@ class AdaptToAmericanSocket:
         return self.original.voltage() / 2
-

Notice how we placed the implements declaration on this adapter class. So -far, we have not achieved anything by using components other than requiring us -to type more. In order for components to be useful, we must use the -component registry. Since AdaptToAmericanSocket implements -IAmericanSocket and regulates the voltage of a -ForeignSocket object, we can register -AdaptToAmericanSocket as an IAmericanSocket adapter -for the ForeignSocket class. It is easier to see how this is -done in code than to describe it:

+

Notice how we placed the implements declaration on this adapter +class. So far, we have not achieved anything by using components other +than requiring us to type more. In order for components to be useful, +we must use the component +registry. Since AdaptToAmericanSocket +implements IAmericanSocket and regulates the voltage of +a ForeignSocket object, we +can register AdaptToAmericanSocket as +an IAmericanSocket adapter for +the ForeignSocket class. It is easier to see how +this is done in code than to describe it:

 from zope.interface import Interface, implements
@@ -321,27 +331,29 @@ False

As you can see, the AmericanSocket instance claims to -implement IAmericanSocket, but the ForeignSocket -does not. If we wanted to use the HairDryer with the -AmericanSocket, we could know that it would be safe to do so by -checking whether it implements IAmericanSocket. However, if we -decide we want to use HairDryer with a ForeignSocket -instance, we must adapt it to IAmericanSocket before -doing so. We use the interface object to do this:

+implement IAmericanSocket, but +the ForeignSocket does not. If we wanted to use +the HairDryer with the AmericanSocket, we +could know that it would be safe to do so by checking whether it +implements IAmericanSocket. However, if we decide we want +to use HairDryer with a ForeignSocket +instance, we must adapt it to IAmericanSocket +before doing so. We use the interface object to do this:

 >>> IAmericanSocket(fs)
 <__main__.AdaptToAmericanSocket instance at 0x1a5120>
-

When calling an interface with an object as an argument, the interface -looks in the adapter registry for an adapter which implements the interface for -the given instance's class. If it finds one, it constructs an instance of the -Adapter class, passing the constructor the original instance, and returns it. -Now the HairDryer can safely be used with the adapted -ForeignSocket. But what happens if we attempt to adapt an object -which already implements IAmericanSocket? We simply get back the -original instance:

+

When calling an interface with an object as an argument, the +interface looks in the adapter registry for an adapter which +implements the interface for the given instance's class. If it finds +one, it constructs an instance of the Adapter class, passing the +constructor the original instance, and returns it. Now +the HairDryer can safely be used with the +adapted ForeignSocket. But what happens if we attempt to +adapt an object which already implements IAmericanSocket? +We simply get back the original instance:

 >>> IAmericanSocket(am)
@@ -395,8 +407,8 @@ class Root(Referenceable):
     implements(IPBRoot)
-

Suppose you have your own class which implements your -IMyInterface interface:

+

Suppose you have your own class which implements +your IMyInterface interface:

 from zope.interface import implements, Interface
@@ -408,9 +420,9 @@ class MyThing:
     implements(IMyInterface)
-

Now if you want to make this class inherit from pb.Root, -the interfaces code will automatically determine that it also implements -IPBRoot:

+

Now if you want to make this class inherit +from pb.Root, the interfaces code will automatically +determine that it also implements IPBRoot:

 from twisted.spread import pb
@@ -429,8 +441,9 @@ class MyThing(pb.Root):
 True
-

If you want MyThing to inherit from pb.Root but -not implement IPBRoot like pb.Root does, +

If you want MyThing to inherit +from pb.Root but not +implement IPBRoot like pb.Root does, use implementOnly:

diff --git a/doc/core/howto/cred.xhtml b/doc/core/howto/cred.xhtml
index f16080b..dae222b 100644
--- a/doc/core/howto/cred.xhtml
+++ b/doc/core/howto/cred.xhtml
@@ -65,12 +65,13 @@ This has only 2 methods -

 
    
 
  • login(credentials, mind, *interfaces)
 
-
    The docstring is quite expansive (see twisted.cred.portal), but in
-brief, this is what you call when you need to call in order to connect
-a user to the system.  Typically you only pass in one interface, and the mind is
-None. The interfaces are the possible interfaces the returned
-avatar is expected to implement, in order of preference.
-The result is a deferred which fires a tuple of:
    
+
    The docstring is quite expansive
+(see twisted.cred.portal), but in brief, this
+is what you call when you need to call in order to connect a user to
+the system.  Typically you only pass in one interface, and the mind
+is None. The interfaces are the possible
+interfaces the returned avatar is expected to implement, in order of
+preference.  The result is a deferred which fires a tuple of:
    
     
      
 	
    • interface the avatar implements (which was one of the interfaces passed in the *interfaces
 tuple)
      • 
@@ -343,11 +344,11 @@ href="tap.xhtml">Writing a twistd plugin document.
      
 
    
      Building a cred plugin
      
 
-
       To build a plugin for cred, you should first define an authType, a short one-word string that defines
-your plugin to the command-line. Once you have this, the convention is
-to create a file named myapp_plugins.py in the
-twisted.plugins module path. 
      
+
       To build a plugin for cred, you should first define
+an authType, a short one-word string that
+defines your plugin to the command-line. Once you have this, the
+convention is to create a file named myapp_plugins.py in
+the twisted.plugins module path. 
      
 
 
       Below is an example file structure for an application that defines
 such a plugin: