Pmwikilib

Summary: Python API for PmWiki
Version: 0.1.1
Prerequisites: python
Status: Beta
Maintainer: Antony Templier
Categories: Python
Users: (view? / edit)
Discussion: Pmwikilib-Talk?

Questions answered by this recipe

How can read and write Pmwiki's pages with a python script.

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

A simple but powerful python API to pmwiki

Pmwikilib is a python module that allow you to manipulate pmwiki's page easily :

  • read, write an protect pages
  • edit public or protected pages (of course you need informations that allow you to do it )
  • access page on local file system or via http protocol on site web
  • generate page history same as pmwiki do when writting, even with local file edition
  • can log errors for debugging purpose

Installation

Download : Pmwikilib-0.1.1.tar.gzΔ (or Pmwikilib-0.1.1.zipΔ)

To install this module on your system :

python setup.py install

or manually extract the directory pmwikilib from the Pmwikilib-0.1.0.tar.gz ( or .zip) where you want, and add the path to that directory to your PYTHONPATH.

Configuration

Usage

Code samples

The PmwikiPage class:

#!/usr/bin/env python
#-*- coding:utf-8 -*-

from pmwikilib.page import PmwikiPage

#Create page
path = '.'
name = 'MyGroup.MyPage'
mypage = PmwikiPage(path, name)
ptext = '(:title My page n°1:)\nHello world !' 
mypage.write_text(ptext)

#Read a page
print mypage.read()

#editing with 2nd method
mypage.text += '\nGoodbye world...'
mypage.write()

Activate logging:

#!/usr/bin/env python
#-*- coding:utf-8 -*-

import sys
import os
from tempfile import gettempdir
import logging

from pmwikilib.page import PmwikiPage

def initlog():
    # the file to log in tmp directory
    log_file = os.path.join( gettempdir(), 'pmwikilib.log')

    #del logfile if exists
    if os.path.exists(log_file):
        os.unlink(log_file)
    #init log
    logging.basicConfig(
        filename=log_file,
        format='%(asctime)s - %(levelname)s - %(message)s',
        filemode='a+',
        level=logging.DEBUG
    )

    logging.info('\n---Start log---\n')

def main():
    p = PmwikiPage('./', 'MyGroup.MyPage2')
    ptext = 'Hello world Toto'
    p.write_text(ptext)

    #Protect the page
    p.change_attr(passwdedit='secret')

if __name__ == '__main__':
   initlog()
   main()

PmwikiPage class public property

text

        Encoded (with charset given) page's content. 
        Only used for input/output, we convert it internally to unicode for 
        doing the job

unicode_text

        Unicode page's content as it used internally.

PmwikiPage class public method

PmwikiPage( path, name )

        Constructor

        @type   path: string
        @param  path: the way to reach the page. If start with 'http://' we 're
                        looking for an URL else for a path on local file system

        @type   name: string
        @param  name: Name formatted as 'GroupName.PageName'

get_name

        return the page's name

check_path

        Check if we can reach the page.

        For web page: Test http connexion and try to guess if the given url is 
        a pmwiki web site.

        For file page: test if path exist and if our rights allow us I/O access

        @rtype  Boolean
        @rparam Indicate if we can access the page.

read(author=None, password=None)

        Return encoded page's content

        Author & password are required for web protected page.

        @type   author: string
        @param  author: author (as $authid) required when page is write 
                        protected and AuthUser is enable

        @type   password: String
        @param  password: password needed by an authentication request when page
                          is write protected

        @rtype  string
        @rparam Encoded content's of an existing page

write_text(text=None, author=None, password=None, charset=None)

        Writting some text to the page.

        Author & password are required for web protected page. Also author is
        used as the author's name of an edition for both web and local file 
        page.

        @type   author: string
        @param  author: author (as $authid) required when page is write 
                        protected and AuthUser is enable

        @type   password: String
        @param  password: password needed by an authentication request when page
                          is write protected

        @type   charset: String
        @param  charset: Character encodind for the page. If not set UTF-8 will
                         be used.

write(author=None, password=None, charset=None)

        Flush the self.text into the page

        Author & password are required for web protected page. Also author is
        used as the author's name of an edition for both web and local file 
        page.

        @type   author: string
        @param  author: author (as $authid) required when page is write 
                        protected and AuthUser is enable

        @type   password: String
        @param  password: password needed by an authentication request when page
                          is write protected

        @type   charset: String
        @param  charset: Character encodind for the page. If not set UTF-8 will
                         be used.

change_attr(author=None, password=None, **attributes)

        Change attributes'page to protect or unprotect the page with reading,
        writting, uploading and changing attributes. Change attributes will add
        an history entry for both web and local file page.

        Author & password are required for web protected page. Also author is
        used as the author's name of an edition for both web and local file 
        page.

        @type   author: string
        @param  author: author (as $authid) required when page is write 
                        protected and AuthUser is enable

        @type   password: String
        @param  password: password needed by an authentication request when page
                          is write protected

        @type   attributes: dict
        @param  attribute: key elts in dict can be 'passwdedit', 'passwdread', 
                           'passwdupload' and 'passwdattr'

set_charset(charset)

        Change internal parameter character encoding of the page.

        Use to convert to unicode when setting the text property and to encode 
        page's content when writting if charset is not given with write or
        write_text method.

        Allow to re-encode page if called just before write or write_text. 

        Note : If only charset is changed before write operation, an history 
        entry will be added for web page but not on a local file page.

Notes

This module is for python2 ( tested with 2.6, 2.7 ) A python3 version should be release one day ...

I use Pmwiki with AuthUser and I use this module in various python scripts for one year. It' s well tested and it's stable in my environnement.

Change log / Release notes

0.1.1 : Just add odict dependency in setup.py 0.1.0 : Initial public release

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

Comments

See discussion at Pmwikilib-Talk?

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.