Python API

This document presents the public API, meaning, the set of functions and classes that matter the most. If you are interested in all the nitty-gritty details, here’s a link to the epydoc documentation for the entire source code: restblog source code

restblog.server

Encapsulates a connection to a blog server and provides a simplified API to manage posts and pages.

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

restblog.server.connect(url='', user='', password='', interactive=False)

connect( url=’‘, user=’‘, password=’‘, interactive=False ) -> Server

Convenience function to create a Server object. This is the preferred method over constructing a Server directly. It would attempt to use the given credentials if not empty. Otherwise, it would look into the .restblog directory, if it exists, to extract the default credentials.

Parameters:

• url: Address of the XMLRPC blog server, e.g. http://your.blog.com/xmlrpc.php
• user: Optional user name.
• password: Optional password.
• interactive: Prompts user for missing credentials like user and/or password when set to True. By default it is set to False meaning that it would use the given credentials and fail if it can’t connect for any reason.

Returns:

A Server instance.

class restblog.server.Server(url, user='', password='')

Server( url, user=’‘, password=’’ ) -> instance

Provides a simplified API to a subset of methods from the various blogging APIs, i.e. Wordpress, MetaWeblog, Blogger, MoveableType. Manages the connection to a blog server using XMLRPC.

Parameters:

• url: Address of the XMLRPC blog server, e.g. http://your.blog.com/xmlrpc.php
• user: Optional user name.
• password: Optional password.

Server.getRecentPostTitles(count=10)

getRecentPostTitles( count=10 ) -> list

Returns a list with minimal information about the most recent posts.

Encapsulates MoveableType function mt.getRecentPostTitles.

Parameters:

• count: Number of posts to retrieve. Default is 10.

Returns:

A list of dictionaries representing data from the post. Including postid, title and dateCreated.

Server.newPost(contents, publish)

newPost( contents, publish ) -> int

Creates a new post.

Encapsulates MetaWeblog function metaWeblog.newPost.

Parameters:

• contents: A dictionary with the keys listed below.

  • title: str
  • description: str
  • mt_excerpt: str
  • mt_text_more: str
  • mt_keywords: list
  • categories: list

• publish: Whether to publish immediately or not. Default is True.

Returns:

An integer with the post ID just created.

Server.editPost(id, contents, publish)

edit( contents, publish ) -> bool

Updates the post with the given id and contents.

Encapsulates MetaWeblog function metaWeblog.editPost.

Parameters:

• contents: A dictionary with the keys listed below.

  • title: str
  • description: str
  • mt_excerpt: str
  • mt_text_more: str
  • mt_keywords: list
  • categories: list

• publish: Whether to publish changes immediately or not. Default is True.

Returns:

True if the update was successful. False otherwise.

Server.deletePost(id, publish)

deletePost( id, publish ) -> bool

Deletes post with the given id.

Encapsulates MetaWeblog function metaWeblog.deletePost.

Parameters:

• id: Post ID to delete.
• publish: Whether to publish the deletion immediately or not. Default is True.

Returns:

True if the deletion was successful. False otherwise.

Server.newPage(contents, publish)

newPage( contents, publish ) -> int

Creates a new page. This function is practically identical to newPost. It receives the same parameters. One note though, contents may have some extra keys that do not quite apply to pages, e.g. tags and categories, but are gracefully ignored by the actual implementation on the server side.

Encapsulates Wordpress function wp.newPage.

Parameters:

• contents: A dictionary with the keys described in newPost.
• publish: Whether to publish immediately or not. Default is True.

Returns:

An integer with the page ID just created.

Server.editPage(id, contents, publish)

editPage( id, contents, publish ) -> bool

Edit page with the given id. This function is practically identical to editPost. It receives the same parameters. One note though, contents may have some extra keys that do not quite apply to pages, e.g. tags and categories, but are gracefully ignored by the actual implementation on the server side.

Encapsulates Wordpress function wp.editPage.

Parameters:

• contents: A dictionary with the keys described in editPost.
• publish: Whether to publish immediately or not. Default is True.

Returns:

True if the update was successful. False otherwise.

restblog.post

Functions to transform and manipulate a restblog post from XHTML.

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

restblog.post.createFormattedPost(file_name)

createFormattedPost( file_name ) -> str

Translates the given file_name into an XHTML document.

Parameters:

• file_name: Input file with a post in reStructuredText format.

Returns the name of a file with the XHTML document.

restblog.post.getPostContents(file_name)

getPostContents( file_name ) -> ( xml.etree.ElementTree.Element, dict )

Extracts the relevant portions of the post from the given XHTML file_name.

Parameters:

• file_name: Name of the XHTML input file name.

Returns a tuple with the following values:

• An xml.etree.ElementTree.Element that contains the post metadata. This is basically the options extracted from the .. restblog:: directive stored in the input reStructuredText file used to produce the given XHTML file_name. See restblog.directives.restblogheader for more information.

• A dictionary with the actual portion of the XHTML document that contains the post contents. Contains the following keys:

  • title: str
  • description: str
  • mt_excerpt: str
  • mt_text_more: str
  • mt_keywords: list
  • categories: list

restblog.directives

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

The restblog directive.

Usage:

.. restblog::
    :type: post or page
    :title: string
    :categories: comma-separated list of strings
    :tags: comma-separated list of strings
    :publish: yes or no
    :id: integer
    :source: yes or no

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

The restblog fullstory directive.

Usage:

.. fullstory::

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

The restblog video directive.

Usage:

.. video:: url

Or:

.. video:: type id

Options:

:width: 400
:height: 300
:fullscreen: yes
:scriptaccess: yes

Options for vimeo only:

:title: yes
:byline: yes
:portrait: yes

Examples:

.. video:: http://vimeo.com/7809605
.. video:: vimeo 7809605
.. video:: http://www.youtube.com/watch?v=37GrbCUvZEM
.. video:: youtube 37GrbCUvZEM

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

Third-party directives

The Pygments reStructuredText directive

This fragment is a Docutils 0.5 directive that renders source code (to HTML only, currently) via Pygments.

To use it, adjust the options below and copy the code into a module that you import on initialization. The code then automatically registers a sourcecode directive that you can use instead of normal code blocks like this:

.. sourcecode:: python

    My code goes here.

If you want to have different code styles, e.g. one with line numbers and one without, add formatters with their names in the VARIANTS dict below. You can invoke them instead of the DEFAULT one by using a directive option:

.. sourcecode:: python
    :linenos:

    My code goes here.

Look at the directive documentation to get all the gory details.

copyright:Copyright 2006-2009 by the Pygments team, see AUTHORS. license:BSD, see LICENSE for details.

restblog.restblog2html

Utility module that converts a reStructuredText file into XHTML. Based on the rst2html script provided by docutils with some hard-coded options that are suitable for restblog.

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

restblog.restblog2html.main(arguments)

main( arguments )

Converts a reStructuredText file into an XHTML document.

Parameters:

• arguments: A list of strings representing the command-line arguments to the rst2html executable, e.g. sys.argv[1:]

restblog.commandline

Command-line interface to restblog.

copyright:Copyright 2010 Luis Artola. license:BSD, see LICENSE.txt for details.

restblog.commandline.run(arguments)

run( arguments )

Parses and executes the given command-line arguments.

Parameters:

• arguments: A list of strings representing the command-line arguments to the restblog executable, e.g. sys.argv[1:]

restblog.commandline.loadCommandByName(name)

loadCommandByName( name ) -> module

Locates and imports a restblog subcommand by the given name.

Subcommands can be imported programmatically like this:

>>> import restblog.commandline
>>> command = restblog.commandline.loadCommandByName( 'list' )
>>> command.run( '--last=10' )

Returns a module object.