welcome to
pyFreenet
Introduction
pyFreenet is a complete API for Python that allows full access to the
Freenet secure/anonymous publishing network.
Within pyFreenet, you'll find a rich toolbox of simple yet powerful
Python classes that will make your Freenet programming job orders of
magnitude faster and easier.
This document aims to acquaint you with the basic top-level classes,
and get you up to speed with the basic concepts.
It does not aim to describe the classes in detail - there's a
comprehensive epydoc-generated Class Reference to take care of that.
You'll notice that the design of these classes lends itself to
experimenting with the classes via the Python Interactive Interpreter.
So just fire up Python, import freenet,
and learn while you hack!
You'll also notice from the classes architecture that there are many
different ways to go about things.
Many classes contain unimethods
- methods that, if invoked statically,
will auto-instantiate the class
just for one operation.
Don't be intimidated with the diversity of this API - just look through
the examples, do some playing around, and choose the styles which feel
best to you.
Note - pyFreenet 0.1 was just a wrapper to the fcptools ezFCPlib Freenet FCP access
library. In pyFreenet 0.2 and later, all dependence on fcptools has been
eliminated, since pyFreenet now does all the required socket
communication internally.
Classes Summary
pyFreenet - package freenet
- contains the following classes:
- site -
entire, high-level freesites
- key - a
single unit of Freenet data
- uri -
the Uniform Resource Indicator (also called 'key address') of a freenet key
- metadata
- information which declares the context of the document (eg MIMEtype)
- fcp -
low level connection to Freenet node for basic key I/O operations
Also, the
following global functions:
- dbr() -
utility function for calculating Date-Based Redirect offsets
- verbosity()
- set verbosity for logging
- connect()
- Initialise connection to Freenet node
- LOGMSG()
- function for logging and filtering error/status/debugging output. Good
to reassign this to your own function when writing GUI programs.
And, the following module variables:
- host -
hostname of Freenet node, default 127.0.0.1
- port -
TCP port of Freenet node's FCP interface - default 8481
- splitsize
- size of splitfiles when inserting large keys - default 256k
- LOGMSG
- ref of the logging function - defaults to a function which prints to
stdout
Between these classes, you should be able to do everything you want
relating to Freenet.
Class Descriptions
site - high-level freesite
objects
freenet.site is an easy class to
use for constructing, inserting and/or retrieving entire freesites. Its
methods take care of generating/interpreting metadata, date-based
redirects, and all other site-management details, allowing you to work
with a high-level concept.
key - manage individual
freenet keys
freenet.key objects are the
individual units of data that get stored into and retrieved from the
Freenet. In other words, the raw 'CHK@',
'KSK@', 'SSK@', 'SVK@' keys and their metadata.
freenet.key is a subclass of MutableString, which means that it
can be treated a lot like regular python strings.
uri - freenet key address
objects
freenet.uri lets you work with Freenet
URI address objects. They're like strings, only smarter.
All freenet keys are addressed
by a freenet uri - 'Uniform Resource Indicator', just as (say) web pages
are referred to by a URL (eg
'http://freenet.sourceforge.net/tiki-index.php?page=ClientProto').
There's plenty of documentation elsewhere within Freenet about Freenet
keys and uris, so I won't duplicate labour here. So it will suffice to
say that the freenet.uri class
allows for easy construction and dissection of Freenet key URIs.
freenet.uri is also subclassed
from MutableString.
metadata - freenet key
structure information
freenet.metadata is a high-level
class that takes all the pain out of handling Freenet key metadata.
Every key that gets inserted
into Freenet may contain metadata
- additional information describing how the key should be handled in
client programs.
Simplistically, metadata is like a 'directory' of 'sub-keys', that
gives instructions on how to fetch these sub-keys. For example, you
might have a key KSK@mykey. The
metadata for this key can contain entries for documents with names alice and bob, telling where the data for
alice and bob can be found. Therefore, when fetching the key KSK@mykey//alice, pyFreenet will
first fetch key KSK@mykey, then
look up document alice in the
metadata, then use that info to retrieve the actual data corresponding
to alice.
But this is a very oversimplified description of metadata. You really
need to study the Freenet Metadata Specification at http://freenet.sourceforge.net/tiki-index.php?page=MetaData
In a lot of ways, it's the smarts and flexibility of metadata that gives
Freenet much of its power.
Back to the class description. freenet.metadata
is a class that lets you:
- construct document metadata
- parse and dissect raw metadata text
- render metadata data strucures into raw text, ready for insertion
into freenet.
freenet.metadata is also
subclassed from MutableString.
fcp - low-level node
interface
freenet.fcp is responsible for
talking via socket connection to our Freenet node.
There are low-level methods for:
- handshaking with the Freenet node
- inserting keys into Freenet
- retrieving keys from Freenet
- creating a new keypair (needed for most freesites)
- computing the CHK hash of a key
Global Functions
connect() establishes the ability
to communicate with a freenet node. Does a basic handshake, to ensure
that the node is healthy and able to fulfil requests, and that the node
exists where we think it does, and will allow us to give it commands.
dbr() is a convenient utility
function is used for computing offset values for Date-Based Redirects,
crucial for processing things like DBR-based freesites.
verbosity() lets you set the verbosity
level for error/status/debugging information. Setting higher values lets
you see more of what's going on, at the price of a noisier stdout.
Setting this to level 4, 'debug', gives you more information than you're
likely to ever want or need.
LOGMSG() is the function responsible for
outputting error, status and debugging information. By default, it will
just be a filtered print to
stdout. If you're writing GUI software, you might want to override this
function with the statement freenet.LOGMSG
= mylogfunc. Note that LOGMSG
takes 2 arguments - verbosity level (0=Critical, 1=Normal, 2=Verbose,
3=Debug), and msg - a plain string to be logged.
Global variables
host -
TCP hostname of Freenet node, usually 127.0.0.1
port -
TCP port of Freenet node's FCP interface - usually 8481
splitsize
- size of file chunks, in cases where large files are split into pieces
during insert. Usually 256k
LOGMSG -
see LOGMSG() in Global Functions
Manual
writen Feb-March 2003, by David McNab. Copyright (c) 2003, All rights
reserved.