# djvulibre-python 0.9.3 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.