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.

Context.py

This module implements fluid lets in Python. This is a kind of context where
values are referenced by dynamic name, based on the running thread (each
thread get's it's own namespace). The default dynamic namespace is desktop=0
and cloud=1. Only _html and _xml methods are desktop=1 and cloud=0. You can
override this with beginCloud or beginDesktop (or add other stuff to the
context with begin(...)).

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.

timeoutsocket.py

Just a little hack that adds timeouts to all socket operations.

strptime.py

A cross-system compatible version of strptime. It's written completely
in python and so should work everywhere.

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.

CommandQueue.py
PersistentQueue.py

These are modules that implement command queues that are handled in memory
or in metakit databases. Command queues are for telling background threads
what to do.

Source Code syntax highlightings
--------------------------------

There are several modules that support source highlighting in PyDS.

PyFontify.py
PyHtmlify.py
docpytils.py

These modules implement the pycode directive to highlight Python source
code.

codeblock.py

This module implements language highlighting for 20 languages, using
the SilverCity Python extension module.

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
LinkRewritingHandler.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. LinkRewritingHandler.py is
much like StaticHandler.py, only that it rewrites links to be used in
the preview.

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.

The thread handling itself is actually in Tool.py, but Server.py starts it all
and contains the medusa stuff.

Upstreaming Drivers
-------------------

DriverRegistry.py

This module implements a registry for different upstreaming drivers.

FTPDriver.py
LFSDriver.py
XSSDriver.py

These modules implement upstreaming over XML Storage System (XSSDriver),
FTP (FTPDriver) and simple local file copying (LFSDriver).

Mirroring Infrastructure
------------------------

MirrorRegistry.py

This module implements a registry for different mirroring drivers.

PyCSSearchMirror.py

This module implements a mirror for usage of the PyCS search engine.

MirrorTool.py

This tool manages the mirror facilities.

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.

AccessRestrictionsTool.py

This implements a frontend for the AccessRestrictions API of the PyCS. You
can define rules with associated users for your weblog.

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.

EnclosureTool.py

This tool implements hooks into the aggregator and the weblog for handling
of RSS enclosures.

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.

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).

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.

MeshTool.py

This is a helper tool to provide functionality to register for stray link
resolving. Stray links are links in restructured text that are not resolved
directly in the text, but kept "open". This tool let's other tools register
for such resolving, so that for example titles as links point to their
item.

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.

PingTool.py

This tool manages pings to several different server types. Pings tell the
server that parts of your page have updated. This is used for example for
weblogs.com or blo.gs.

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.

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.

TrackbackTool.py

This tool implements the trackback ping protocol to allow weblog posts
to set back-references in outside websites.

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. Additionally it associates
ent:cloud and ent:topic to 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.

BlogmarkTool.py

This manages a weblog that is tailored for simple link lists. It's a mix
of weblog and bookmarks, that's where the name comes from.

WikiTool.py

This manages wiki pages. This is not a real wiki, as it is only accessible
from the desktop. It's more like the static site stuff in Radio, only it
uses restructured text.

ZineTool.py

This tool allows one to create webzines. It's something like a story
tool with substories.