# python-djvulibre 0.8.4 documentation

## Document pages

class `djvu.decode.``DocumentPages`

  Pages of a document.

  Use `Document.pages` to obtain instances of this class.

  Page indexing is zero-based, i.e. `pages``[0]` stands for the first page.

  `len(pages)` might return 1 when called before receiving a `DocInfoMessage`.

class `djvu.decode.``Page`

  Page of a document.

  Use `Document.pages``[N]` to obtain instances of this class.

  `document`

    Return type: | `Document`

  `file`

    Returns: | a file associated with the page.
    Return type: | `File`.

  `n`

    Returns: | the page number.

    Page indexing is zero-based, i.e. 0 stands for the very first page.

  `thumbnail`

    Returns: | a thumbnail for the page.
    Return type: | `Thumbnail`.

  `get_info`([wait=1])

    Attempt to obtain information about the page without decoding the page.

    If wait is true, wait until the information is available.

    If the information is not available, raise `NotAvailable` exception. Then, start fetching the page data, which causes emission of `PageInfoMessage` messages with empty `page_job`.

    Raises:

    - NotAvailable – see above.
    - JobFailed – on failure.

  `width`

    Returns: | the page width, in pixels.

    Raises:

    - NotAvailable – see `get_info()`.
    - JobFailed – on failure.

  `height`

    Returns: | the page height, in pixels.

    Raises:

    - NotAvailable – see `get_info()`.
    - JobFailed – on failure.

  `size`

    Returns: | `(page.width, page.height)`

    Raises:

    - NotAvailable – see `get_info()`.
    - JobFailed – on failure.

  `dpi`

    Returns: | the page resolution, in pixels per inch.

    Raises:

    - NotAvailable – see `get_info()`.
    - JobFailed – on failure.

  `rotation`

    Returns: | the initial page rotation, in degrees.

    Raises:

    - NotAvailable – see `get_info()`.
    - JobFailed – on failure.

  `version`

    Returns: | the page version.

    Raises:

    - NotAvailable – see `get_info()`.
    - JobFailed – on failure.

  `dump`

    Returns: | a text describing the contents of the page using the same format as the `djvudump` command.

    If the information is not available, raise `NotAvailable` exception. Then `PageInfoMessage` messages with empty `page_job` may be emitted.

    Raises: | NotAvailable – see above.

  `decode`([wait=1])

    Initiate data transfer and decoding threads for the page.

    If wait is true, wait until the job is done.

    Return type: | `PageJob`.

    Raises:

    - NotAvailable – if called before receiving the `DocInfoMessage`.
    - JobFailed – if document decoding failed.

  `annotations`

    Return type: | `PageAnnotations`

  `text`

    Return type: | `PageText`

class `djvu.decode.``PageJob`

  Inheritance diagram:

  A page decoding job.

  Use `Page.decode()` to obtain instances of this class.

  `width`

    Returns: | the page width in pixels.
    Raises: | NotAvailable – before receiving a `PageInfoMessage`.

  `height`

    Returns: | the page height in pixels.
    Raises: | NotAvailable – before receiving a `PageInfoMessage`.

  `size`

    Returns: | `(page_job.width, page_job.height)`
    Raises: | NotAvailable – before receiving a `PageInfoMessage`.

  `dpi`

    Returns: | the page resolution in pixels per inch.
    Raises: | NotAvailable – before receiving a `PageInfoMessage`.

  `gamma`

    Returns: | the gamma of the display for which this page was designed.
    Raises: | NotAvailable – before receiving a `PageInfoMessage`.

  `version`

    Returns: | the version of the DjVu file format.
    Raises: | NotAvailable – before receiving a `PageInfoMessage`.

  `type`

    Returns: | the type of the page data.

    Possible values are:

    `PAGE_TYPE_UNKNOWN`
    `PAGE_TYPE_BITONAL`
    `PAGE_TYPE_PHOTO`
    `PAGE_TYPE_COMPOUND`

    Raises: | NotAvailable – before receiving a `PageInfoMessage`.

  `initial_rotation`

    Returns: | the counter-clockwise page rotation angle (in degrees) specified by the orientation flags in the DjVu file.

    Warning

    This is useful because `maparea` coordinates in the annotation chunks are expressed relative to the rotated coordinates whereas text coordinates in the hidden text data are expressed relative to the unrotated coordinates.

  `rotation`

    Returns: | the counter-clockwise rotation angle (in degrees) for the page.

    The rotation is automatically taken into account by `render()` method and `width` and `height` properties.

  `render`(self, mode, page_rect, render_rect, pixel_format[, row_alignment=1][, buffer=None])

    Render a segment of a page with arbitrary scale. mode indicates which image layers should be rendered:

    - `RENDER_COLOR`, or
    - `RENDER_BLACK`, or
    - `RENDER_COLOR_ONLY`, or
    - `RENDER_MASK_ONLY`, or
    - `RENDER_BACKGROUND`, or
    - `RENDER_FOREGROUND`.

    Conceptually this method renders the full page into a rectangle page_rect and copies the pixels specified by rectangle render_rect into a buffer. The actual code is much more efficient than that.

    pixel_format (a `PixelFormat` instance) specifies the expected pixel format. Each row will start at row_alignment bytes boundary.

    Data will be saved to the provided buffer or to a newly created string.

    This method makes a best effort to compute an image that reflects the most recently decoded data.

    Raises: | NotAvailable – to indicate that no image could be computed at this point.

class `djvu.decode.``Thumbnail`

  Thumbnail for a page.

  Use `Page.thumbnail` to obtain instances of this class.

  `page`

    Returns: | the page.

  `status`

    Determine whether the thumbnail is available.

    Returns: | a `JobException` subclass indicating the current job status.

  `calculate`()

    Determine whether the thumbnail is available. If it’s not, initiate the thumbnail calculating job. Regardless of its success, the completion of the job is signalled by a subsequent `ThumbnailMessage`.

    Return a `JobException` subclass indicating the current job status.

  `render`((w0, h0)[, pixel_format][, row_alignment=1][, dry_run=False][, buffer=None])

    Render the thumbnail:

    - not larger than w0 × h0 pixels;
    - using the pixel_format (a `PixelFormat` instance) pixel format;
    - with each row starting at row_alignment bytes boundary;
    - into the provided buffer or to a newly created string.

    Returns: | a ((w1, h1, row_size), data) tuple.

    - w1 and h1 are actual thumbnail dimensions in pixels (w1 ≤ w0 and h1 ≤ h0);
    - row_size is length of each image row, in bytes;
    - data is `None` if dry_run is true; otherwise is contains the actual image data.

    Raises: | NotAvailable – when no thumbnail is available.