welcome to

pyFreenet

where Python meets Freedom!


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:
Also, the following global functions:
And, the following module variables:
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:
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:


Global Functions

connect()

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

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

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

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.