Event model

The DDJVU API provides for efficiently decoding and displaying DjVu documents. It provides for displaying images without waiting for the complete DjVu data. Images can be displayed as soon as sufficient data is available. A higher quality image might later be displayed when further data is available. The DjVu library achieves this using a complicated scheme involving multiple threads. The DDJVU API hides this complexity with a familiar event model.

djvu.decode.DDJVU_VERSION

Version of the DDJVU API.

class djvu.decode.Context(argv0)

handle_message(message)

This method is called, in a separate thread, for every received message, before any blocking method finishes.

By default do something roughly equivalent to:

if message.job is not None:
   message.job.message_queue.put(message)
elif message.document is not None:
   message.document.message_queue.put(message)
else:
   message.context.message_queue.put(message)

You may want to override this method to change this behaviour.

All exceptions raised by this method will be ignored.

message_queue

Return the internal message queue.

get_message([wait=True])

Get message from the internal context queue.

Returns:

a Message instance

Returns:

None if wait is false and no message is available.

new_document(uri[, cache=True])

Creates a decoder for a DjVu document and starts decoding. This method returns immediately. The decoding job then generates messages to request the raw data and to indicate the state of the decoding process.

uri specifies an optional URI for the document. The URI follows the usual syntax (protocol://machine/path). It should not end with a slash. It only serves two purposes:

• The URI is used as a key for the cache of decoded pages.

• The URI is used to document NewStreamMessage messages.

Setting argument cache to a true value indicates that decoded pages should be cached when possible.

It is important to understand that the URI is not used to access the data. The document generates NewStreamMessage messages to indicate which data is needed. The caller must then provide the raw data using a NewStreamMessage.stream object.

class djvu.decode.FileUri(filename)

To open a local file, provide a FileUri instance as an uri.

Localized characters in uri should be in URI-encoded.

Return type:

Document

Raises:

JobFailed – on failure.

cache_size

clear_cache()

class djvu.decode.Job

A job.

get_message([wait=True])

Get message from the internal job queue.

Returns:

a Message instance.

Returns:

None if wait is false and no message is available.

is_done

Indicate whether the decoding job is done.

is_error

Indicate whether the decoding job is done.

message_queue

Returns:

the internal message queue.

status

Returns:

a JobException subclass indicating the job status.

stop()

Attempt to cancel the job.

This is a best effort method. There no guarantee that the job will actually stop.

wait()

Wait until the job is done.