Written by Bill Bumgarner <bbum@friday.com> using the ObjC module for Python. Please report all bugs, patches, and requests to <bbum@friday.com>.
PLEASE see the TODO section before adding any services!!!!
Demonstration
-------------
Before invoking this demo, one must build a custom python binary (or all of the modules as dynamically loadable extensions). Once the binary/modules are built, cd into Demo/ObjC/PyServices:
1. copy PyServices.services to ~/Library/Services/
2. make_services -v | open
This will recompile all of the NEXTSTEP services for your account. The
-v flag will cause a summary of all services to be spewed to stdout.
Search for 'PSDaemon' in the result; you should see several services
with the port 'PyServices'.
Quit and restart Edit.app; the services menu should now include a
'PyServices/' entry with several actions. They will not respond
until you start the daemon by hand [unless you go for a full install].
[That should be all one line]. The above will start the services daemon.
4. Go to Edit. Create a new document. Copy the following URL into it:
http://www.friday.com/hello.txt
Select the URL. Select Services->PyServices->Expand URL.
5. The daemon does not respond to Ctrl-C. To kill, either Ctrl-z and
kill %, or select some text and select PyServices->Kill Daemon.
Kill Daemon actually does something very interesting-- it causes
the daemon to fork and invoke the kill from the child. That way,
the parent successfully returns from the service handler before
dieing. The child doesn't currently but should really sleep at
least a second before killing the parent.
Full Installation
-----------------
If you have decided that having python implemented services really is a very useful thing, then this is how you can achieve a full installation that launches automatically when you log in. If you want the installation to be available for everyone, substitute /LocalLibrary/ for all occurrences of ~/Library:
1. Make the custom python binary or modules. I would suggest building
a custom, statically linked python executable with the name 'pyobjc'.
Ie; from the root level after the 'make -f Misc/Makefile.pre.in boot',
do:
make static TARGET=pyobjc
This will yield a binary named pyobjc that is compatible with
the installed python 1.4 library, but has all of the stuff from
the PyObjc project statically linked in.
Copy 'pyobjc' to /usr/local/bin/
2. cd Demo/ObjC/PyServices
3. Copy PyServices.services to ~/Library/Services/ and 'make_services'
There are two command line switches that can be used to customize where pyservicesdaemon.py looks for services implementations and library files. Both can be specified any number of times and the order will determine the order in which the various directories will be scanned for library files and services implementations.
--lib-path directory: add directory to sys.path
--services-path directory: search directory for services implementations
How the daemon finds a services implementation
----------------------------------------------
The file PyServices.services defines all of the current services implemented by the daemon. Each service has a UserData field that is passed to the daemon whenever a service is invoked. Compare the UserData field to the structure of the PyServicesHandler directory; the UserData field specifies the path to the Python file that implements the named service! In the future, the UserData field will be able to contain more than just the path.
Upon receipt of a service request, the daemon looks in each of the directories specified by the --services-path directive for a python file with the same name & relative path (below the handler directory) as that specified by the UserData field. It is smart enough to load the compiled version as long as it is newer than the non-compiled version.
By default, the paths ~/Library/PyServices/PyServicesHandlers and /LocalLibrary/PyServices/PyServicesHandlers are scanned.
Any support packages can be placed in the ~/Library/PyServices/lib directory-- either as a ni based package (see PyServicesPackage and how it is referred to in the various PSDaemon/*.py services implementations) or as a plain old imported module.
Adding New Services
-------------------
Adding new services is easy, though not nearly as automatic as it should be.
1. Create a services description:
##
## Hello World Service
##
Message: forwardService
Deactivate Requestor: NO
Port: PyServices
Menu Item: Demo/Hello World
Timeout: 10000
User Data: Demo/Hello World
Send Type: NeXT plain ascii pasteboard type
Return Type: NeXT plain ascii pasteboard type
Save the above to-- say-- ~/Library/Services/Demo.services
2. Update system servics:
make_services
3. make the Demo services implementation directory:
5. Quit and Restart Edit [to update the services menu item]. Create a new
window. Type a bit of garbage into it. Select garbage.
Services->Demo->Hello World
Additional Notes
----------------
PyServices->Clear Cache removes all handler entries from the handler cache in wtihin the handler dispatcher. All subsequent services requests will cause the corresponding services python code to be reloaded. This is extremely handy when developping new services.
The first argument to all services handler functions is the handler that dispatched the service. This handler has some additional API and behaviour that you might find useful (and is not immediately obvious from the examples):
By importing the PyServicesHandler module from the PyServicesPackage package, you will have access to PyServicesHandler.VisibleError. Raising an exception of type PyServicesHandler.VisibleError will cause the exception's value to be used as the error string for the original service request. See PSDaemon/Test.py for an example.
The method getHandlerForService() takes a single argument that is typically the UserData field's value. If one desires to have several services implemented by a single handler, one can simply provide stub handlers that invoke handler.getHandlerForService() with the path (relative to one of the paths in servicesPaths.
The method forkAndInvoke() takes a single function as an argument. The function takes a single argument-- the process id of the parent. forkAndInvoke() can be used to invoke long running processes or to implement services that invoke other services. Since services requests are serialized-- ie; only one service can be handled at a time-- any service that invokes other services or service-like mechanisms must not do so from the parent process.
The servicesPaths attributes contains a list of all the paths upon which the dispatcher will search for services handlers.
The deamon attribute contains a reference to the PyServicesDaemon object that 'owns' the handler instance. There really isn't much to the PyServicesDaemon class.
Because of the way the cache works, services can easily save 'state' across calls by accumulating said state within the handler's module's namespace. It is not possible to add variables to the handler-- unless you really know what you are doing.
TODO
----
- provide automatic mechanism for compiling and installing the .services file
- create UI for editing services (see TickleServices).
- add more PSDaemon/ services for analyzing the state of the server
- add package support to services [such that a set of services may have a designated initializer that is automatically invoked when any of the services within the package is referenced].
