Package CedarBackup2 :: Package writers :: Module util :: Class IsoImage
[show private | hide private]
[frames | no frames]

Type IsoImage

object --+
         |
        IsoImage


Represents an ISO filesystem image.

Summary

This object represents an ISO 9660 filesystem image. It is implemented in terms of the mkisofs program, which has been ported to many operating systems and platforms. A "sensible subset" of the mkisofs functionality is made available through the public interface, allowing callers to set a variety of basic options such as publisher id, application id, etc. as well as specify exactly which files and directories they want included in their image.

By default, the image is created using the Rock Ridge protocol (using the -r option to mkisofs) because Rock Ridge discs are generally more useful on UN*X filesystems than standard ISO 9660 images. However, callers can fall back to the default mkisofs functionality by setting the useRockRidge instance variable to False. Note, however, that this option is not well-tested.

Where Files and Directories are Placed in the Image

Although this class is implemented in terms of the mkisofs program, its standard "image contents" semantics are slightly different than the original mkisofs semantics. The difference is that files and directories are added to the image with some additional information about their source directory kept intact.

As an example, suppose you add the file /etc/profile to your image and you do not configure a graft point. The file /profile will be created in the image. The behavior for directories is similar. For instance, suppose that you add /etc/X11 to the image and do not configure a graft point. In this case, the directory /X11 will be created in the image, even if the original /etc/X11 directory is empty. This behavior differs from the standard mkisofs behavior!

If a graft point is configured, it will be used to modify the point at which a file or directory is added into an image. Using the examples from above, let's assume you set a graft point of base when adding /etc/profile and /etc/X11 to your image. In this case, the file /base/profile and the directory /base/X11 would be added to the image.

I feel that this behavior is more consistent than the original mkisofs behavior. However, to be fair, it is not quite as flexible, and some users might not like it. For this reason, the contentsOnly parameter to the addEntry method can be used to revert to the original behavior if desired.
Method Summary
  __init__(self, device, boundaries, graftPoint)
Initializes an empty ISO image object.
  addEntry(self, path, graftPoint, override, contentsOnly)
Adds an individual file or directory into the ISO image.
  getEstimatedSize(self)
Returns the estimated size (in bytes) of the ISO image.
  writeImage(self, imagePath)
Writes this image to disk using the image path.
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __repr__(x)
x.__repr__() <==> repr(x)
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value
  __str__(x)
x.__str__() <==> str(x)

Property Summary
  device: Device that image will be written to (device path or SCSI id).
  boundaries: Session boundaries as required by mkisofs.
  graftPoint: Default image-wide graft point (see addEntry for details).
  useRockRidge: Indicates whether to use RockRidge (default is True).
  applicationId: Optionally specifies the ISO header application id value.
  biblioFile: Optionally specifies the ISO bibliographic file name.
  publisherId: Optionally specifies the ISO header publisher id value.
  preparerId: Optionally specifies the ISO header preparer id value.
  volumeId: Optionally specifies the ISO header volume id value.

Instance Method Details

__init__(self, device=None, boundaries=None, graftPoint=None)
(Constructor)

Initializes an empty ISO image object.

Only the most commonly-used configuration items can be set using this constructor. If you have a need to change the others, do so immediately after creating your object.

The device and boundaries values are both required in order to write multisession discs. If either is missing or None, a multisession disc will not be written. The boundaries tuple is in terms of ISO sectors, as built by an image writer class and returned in a writer.MediaCapacity object.
Parameters:
device - Name of the device that the image will be written to
           (type=Either be a filesystem path or a SCSI address)
boundaries - Session boundaries as required by mkisofs
           (type=Tuple (last_sess_start,next_sess_start) as returned from cdrecord -msinfo, or None)
graftPoint - Default graft point for this page.
           (type=String representing a graft point path (see addEntry).)
Overrides:
__builtin__.object.__init__

addEntry(self, path, graftPoint=None, override=False, contentsOnly=False)

Adds an individual file or directory into the ISO image.

The path must exist and must be a file or a directory. By default, the entry will be placed into the image at the root directory, but this behavior can be overridden using the graftPoint parameter or instance variable.

You can use the contentsOnly behavior to revert to the "original" mkisofs behavior for adding directories, which is to add only the items within the directory, and not the directory itself.
Parameters:
path - File or directory to be added to the image
           (type=String representing a path on disk)
graftPoint - Graft point to be used when adding this entry
           (type=String representing a graft point path, as described above)
override - Override an existing entry with the same path.
           (type=Boolean true/false)
contentsOnly - Add directory contents only (standard mkisofs behavior).
           (type=Boolean true/false)
Raises:
ValueError - If path is not a file or directory, or does not exist.
ValueError - If the path has already been added, and override is not set.
ValueError - If a path cannot be encoded properly.

Notes:

  • Things get odd if you try to add a directory to an image that will be written to a multisession disc, and the same directory already exists in an earlier session on that disc. Not all of the data gets written. You really wouldn't want to do this anyway, I guess.
  • An exception will be thrown if the path has already been added to the image, unless the override parameter is set to True.
  • The method graftPoints parameter overrides the object-wide instance variable. If neither the method parameter or object-wide value is set, the path will be written at the image root. The graft point behavior is determined by the value which is in effect at the time this method is called, so you must set the object-wide value before calling this method for the first time, or your image may not be consistent.
  • You cannot use the local graftPoint parameter to "turn off" an object-wide instance variable by setting it to None. Python's default argument functionality buys us a lot, but it can't make this method psychic. :)

getEstimatedSize(self)

Returns the estimated size (in bytes) of the ISO image.

This is implemented via the -print-size option to mkisofs, so it might take a bit of time to execute. However, the result is as accurate as we can get, since it takes into account all of the ISO overhead, the true cost of directories in the structure, etc, etc.
Returns:
Estimated size of the image, in bytes.
Raises:
IOError - If there is a problem calling mkisofs.
ValueError - If there are no filesystem entries in the image

writeImage(self, imagePath)

Writes this image to disk using the image path.
Parameters:
imagePath - Path to write image out as
           (type=String representing a path on disk)
Raises:
IOError - If there is an error writing the image to disk.
ValueError - If there are no filesystem entries in the image
ValueError - If a path cannot be encoded properly.

Property Details

device

Device that image will be written to (device path or SCSI id).

boundaries

Session boundaries as required by mkisofs.

graftPoint

Default image-wide graft point (see addEntry for details).

useRockRidge

Indicates whether to use RockRidge (default is True).

applicationId

Optionally specifies the ISO header application id value.

biblioFile

Optionally specifies the ISO bibliographic file name.

publisherId

Optionally specifies the ISO header publisher id value.

preparerId

Optionally specifies the ISO header preparer id value.

volumeId

Optionally specifies the ISO header volume id value.

Generated by Epydoc 2.1 on Thu Mar 29 20:58:28 2007 http://epydoc.sf.net