This file documents modules used in PyDS:
=========================================

Helper Modules
--------------

ConfigLoader.py
DefaultConfig.py

These two modules implement the configuration loader and default settings.
The configuration is loaded into a global Variable _PyDS. Actually it's not
only a global, but a builtin, so you can access it everywhere without import.

Stripogram.py

This is a HTML cleaner that is used in several places. Mostly relevant for
MacrosTool, as the stripHTML and safeHTML macros use it.

EXIF.py

This reads EXIF data from images.

SOAP.py

This is a SOAP client and server implementation that is used to implement
the SOAP functionality.

Translation.py

This is a simple gettext wrapper class to handle translation of text messages.
Those text messages are called with _('....') and to create the translation
table, there is the make_msgs.py tool.

StructuredText.py

This is a hack to implement reStructuredText as a text processing mechanism
for postings. It uses the DocUtils package.

The server architecture
-----------------------

Daemonize.py

A helper module to implement standard posix daemon behaviour (disconnect,
run in background, redirect output).

SOAPHandler.py
XMLRPCHandler.py
StaticHandler.py

These are handler modules for various stuff. SOAP and XMLRPC are for xml
based RPC calls, StaticHandler.py is for static content in the static and
the images subfolder of the users www folder.

Server.py

This initializes the server and starts everything. This instantiates and
runs all included tools. Usually you put your own tools into one of the
dynamic tools folders and this module automatically loads them. Only system
tools are imported directly in Server.py. The initialization is in the way
that first all Tools are imported, next all tools _initdb method is called,
then all tools _initopts method is called and then all tools _initthread
are started. Then all tools are installed as handlers into the medusa server
and the server asyncloop is started.

Additional XMLRPC APIs
----------------------

BloggerAPI.py
MetaWeblogAPI.py

These modules implement standard APIs as good as they can in the PyDS
context. Usually you are far better off with using native APIs, but these
exist to allow the usage of third party tools that don't care for PyDS
native APIs.

The PyDS tools
--------------

Tool.py

This contains the base class for the tools and an implementation of the
private request class for tool invocations. Much of the standard functionality
is implemented here.

AggregatorTool.py

This handles the news aggregator. It includes everything needed to parse RSS
and RDF feeds and store items in the database. It uses the DownstreamTool for
all access to the internet.

CalendarTool.py

This manages calendar rendering. It has a cache of calendar data, so it doesn't
need to scan the tools databases on every invocation. You usually call into
this module from your own code when you have changes to your database that
are connected to calendar rendering.

DocumentationTool.py

This tool automatically extracts documentation for tools that have hasAPI set
to a true value. So if your tool doesn't have an API worth exposing to the
user, just set self.hasAPI to a false value in your _initopts!

DownstreamTool.py

This tool manages all downloads from the internet. It supports HTTP proxies
and manages it's own cache of files, so it doesn't need to pull down content
that's already available.

EventsTool.py

This is the eventlog. All tools can log into the eventlog and the messages
are shown with this tool. On getRecentEvents, events older than 24h are
automatically purged from the database.

MacrosTool.py

This is the central place for usefull macros. Many macros are predefined, but
you have additionally the option to define own macros via the web interface.
There is no distinction between the predefined macros or user defined macros.

NavigationTool.py

This manages the navigation part of the homepage. It's just a simple list
of links of different types with a very simple rendering of the menu.

NuggetsTool.py

Nuggets are much like macros. Only difference is, they are written in the
Cheetah template language and not in Python (as macros are). Another difference
is that Nuggets can be active. Active nuggets are not rendered inline, but
only a JavaScript shim is rendered. This JavaScript code pulls in the content
of the separately rendered nugget. This allows partial rerendering of content
when combined with timer triggered rerendering of active nuggets.

PasswordTool.py

This tool manages passwords to be used in nuggets, stories or macros. This is
to prevent accidental upstreaming of passwords when rendering the source
of an object or when upstreaming your backup files.

PictureTool.py

This manages a photographic blog. It's very similar in feature to the standard
weblog, only that it manages only one category and that it manages primarily
pictures. Pictures carry a local template each, so you can render each
picture differently.

PreferencesTool.py

All preferences are managed from this tool. There are standard preferences that
are directly managed by this tool and there are preferences panes that are
only indirectly managed from this tool but are located in the original tool.
This enables you to hook up your preferences pane into the main preferences
application.

RenderTool.py

This manages multiple rendering queues for simple "one object, one file and
one global index" tools, so that those don't need their own background thread.
It's mainly to help developers to set up simple tools without the need to
have their own thread handling.

ShortcutTool.py

This manages shortcuts for text renderings. Every text processed with one
of the _Request.render* methods uses these shortcuts to expand text.

StatusTool.py

This is just a handy way to pack all _status method together in one central
place to show to the user.

StoryTool.py

Stories are just longer postings with a very simple index. The idea is to
put essays and special contents that is not time connected into this tool.
It is often used to create special pages like blogrolls or overviews, as you
can make full use of the Cheetah template language in the stories and you can
trigger them via the TimerTool.

ExternalStoryTool.py

External stories are stories that reside in the filesystem. This enables one
to edit those stories with his favorite editor instead through the browser
edit box. This can be used to automatically maintain pages that are built
by external tools (for example outliners).

ThemesTool.py

This is a tool to manage the layout of your pages (both desktop and cloud).
You can edit your templates with this tool through your desktop website and
bundle pages together to send your layout to others.

TimerTool.py

The timer manages timed execution of events. Tools can hook up methods into
the timer to enable the user to execute them regularily. This is used to
automatically refresh story or active nugget contents.

TopicExchangeTool.py

TopicExchange is a way to implement central lists of postings that are
relevant to a specific topic. This tool hooks up with the WeblogTool to enable
you to ping TopicExchange on new postings.

UpstreamTool.py

This tool handles all upstreaming to the cloud. It's the counterpart to the
DownstreamTool and it handles all SOAP and XMLRPC client instantiation and
proxy handling.

UserTool.py

Manage your users that are allowed to access the system remotely here. You can
implement new authorization methods in this module.

WeblogTool.py

This manages a standard weblog with calendar rendering, categories, and lots
of hooks to enable tools to change processing.

