CedarBackup3.writers.util.IsoImage

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

# Class IsoImage

source code

    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.

Instance Methods | [hide private]
__init__(self, device=None, boundaries=None, graftPoint=None) Initializes an empty ISO image object. | source code
addEntry(self, path, graftPoint=None, override=False, contentsOnly=False) Adds an individual file or directory into the ISO image. | source code
getEstimatedSize(self) Returns the estimated size (in bytes) of the ISO image. | source code
_getEstimatedSize(self, entries) Returns the estimated size (in bytes) for the passed-in entries dictionary. | source code
writeImage(self, imagePath) Writes this image to disk using the image path. | source code
_buildGeneralArgs(self) Builds a list of general arguments to be passed to a `mkisofs` command. | source code
_buildSizeArgs(self, entries) Builds a list of arguments to be passed to a `mkisofs` command. | source code
_buildWriteArgs(self, entries, imagePath) Builds a list of arguments to be passed to a `mkisofs` command. | source code
_setDevice(self, value) Property target used to set the device value. | source code
_getDevice(self) Property target used to get the device value. | source code
_setBoundaries(self, value) Property target used to set the boundaries tuple. | source code
_getBoundaries(self) Property target used to get the boundaries value. | source code
_setGraftPoint(self, value) Property target used to set the graft point. | source code
_getGraftPoint(self) Property target used to get the graft point. | source code
_setUseRockRidge(self, value) Property target used to set the use RockRidge flag. | source code
_getUseRockRidge(self) Property target used to get the use RockRidge flag. | source code
_setApplicationId(self, value) Property target used to set the application id. | source code
_getApplicationId(self) Property target used to get the application id. | source code
_setBiblioFile(self, value) Property target used to set the biblio file. | source code
_getBiblioFile(self) Property target used to get the biblio file. | source code
_setPublisherId(self, value) Property target used to set the publisher id. | source code
_getPublisherId(self) Property target used to get the publisher id. | source code
_setPreparerId(self, value) Property target used to set the preparer id. | source code
_getPreparerId(self) Property target used to get the preparer id. | source code
_setVolumeId(self, value) Property target used to set the volume id. | source code
_getVolumeId(self) Property target used to get the volume id. | source code
Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Static Methods | [hide private]
_buildDirEntries(entries) Uses an entries dictionary to build a list of directory locations for use by `mkisofs`. | source code

Properties | [hide private]
| 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.
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, device=None, boundaries=None, graftPoint=None) (Constructor) | source code
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` (Either be a filesystem path or a SCSI address) - Name of the device that the image will be written to `boundaries` (Tuple `(last_sess_start,next_sess_start)` as returned from `cdrecord -msinfo`, or `None`) - Session boundaries as required by `mkisofs` `graftPoint` (String representing a graft point path (see addEntry).) - Default graft point for this page. Overrides: object.__init__

### addEntry(self, path, graftPoint=None, override=False, contentsOnly=False) | source code
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` (String representing a path on disk) - File or directory to be added to the image `graftPoint` (String representing a graft point path, as described above) - Graft point to be used when adding this entry `override` (Boolean true/false) - Override an existing entry with the same path. `contentsOnly` (Boolean true/false) - Add directory contents only (standard `mkisofs` behavior). 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) | source code
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

### _getEstimatedSize(self, entries) | source code
Returns the estimated size (in bytes) for the passed-in entries dictionary. Returns: Estimated size of the image, in bytes. Raises: `IOError` - If there is a problem calling `mkisofs`.

### writeImage(self, imagePath) | source code
Writes this image to disk using the image path. Parameters: `imagePath` (String representing a path on disk) - Path to write image out as 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.

### _buildDirEntries(entries) Static Method | source code
Uses an entries dictionary to build a list of directory locations for use by `mkisofs`. We build a list of entries that can be passed to `mkisofs`. Each entry is either raw (if no graft point was configured) or in graft-point form as described above (if a graft point was configured). The dictionary keys are the path names, and the values are the graft points, if any. Parameters: `entries` - Dictionary of image entries (i.e. self.entries) Returns: List of directory locations for use by `mkisofs`

### _buildGeneralArgs(self) | source code
Builds a list of general arguments to be passed to a `mkisofs` command. The various instance variables (`applicationId`, etc.) are filled into the list of arguments if they are set. By default, we will build a RockRidge disc. If you decide to change this, think hard about whether you know what you're doing. This option is not well-tested. Returns: List suitable for passing to util.executeCommand as `args`.

### _buildSizeArgs(self, entries) | source code
Builds a list of arguments to be passed to a `mkisofs` command. The various instance variables (`applicationId`, etc.) are filled into the list of arguments if they are set. The command will be built to just return size output (a simple count of sectors via the `-print-size` option), rather than an image file on disk. By default, we will build a RockRidge disc. If you decide to change this, think hard about whether you know what you're doing. This option is not well-tested. Parameters: `entries` - Dictionary of image entries (i.e. self.entries) Returns: List suitable for passing to util.executeCommand as `args`.

### _buildWriteArgs(self, entries, imagePath) | source code
Builds a list of arguments to be passed to a `mkisofs` command. The various instance variables (`applicationId`, etc.) are filled into the list of arguments if they are set. The command will be built to write an image to disk. By default, we will build a RockRidge disc. If you decide to change this, think hard about whether you know what you're doing. This option is not well-tested. Parameters: `entries` - Dictionary of image entries (i.e. self.entries) `imagePath` (String representing a path on disk) - Path to write image out as Returns: List suitable for passing to util.executeCommand as `args`.

### _setDevice(self, value) | source code
Property target used to set the device value. If not `None`, the value can be either an absolute path or a SCSI id. Raises: `ValueError` - If the value is not valid

### _setBoundaries(self, value) | source code
Property target used to set the boundaries tuple. If not `None`, the value must be a tuple of two integers. Raises: `ValueError` - If the tuple values are not integers. `IndexError` - If the tuple does not contain enough elements.

### _setGraftPoint(self, value) | source code
Property target used to set the graft point. The value must be a non-empty string if it is not `None`. Raises: `ValueError` - If the value is an empty string.

### _setUseRockRidge(self, value) | source code
Property target used to set the use RockRidge flag. No validations, but we normalize the value to `True` or `False`.

### _setApplicationId(self, value) | source code
Property target used to set the application id. The value must be a non-empty string if it is not `None`. Raises: `ValueError` - If the value is an empty string.

### _setBiblioFile(self, value) | source code
Property target used to set the biblio file. The value must be a non-empty string if it is not `None`. Raises: `ValueError` - If the value is an empty string.

### _setPublisherId(self, value) | source code
Property target used to set the publisher id. The value must be a non-empty string if it is not `None`. Raises: `ValueError` - If the value is an empty string.

### _setPreparerId(self, value) | source code
Property target used to set the preparer id. The value must be a non-empty string if it is not `None`. Raises: `ValueError` - If the value is an empty string.

### _setVolumeId(self, value) | source code
Property target used to set the volume id. The value must be a non-empty string if it is not `None`. Raises: `ValueError` - If the value is an empty string.

Property Details | [hide private]

### device Device that image will be written to (device path or SCSI id). Get Method: _getDevice(self) - Property target used to get the device value. Set Method: _setDevice(self, value) - Property target used to set the device value.

### boundaries Session boundaries as required by `mkisofs`. Get Method: _getBoundaries(self) - Property target used to get the boundaries value. Set Method: _setBoundaries(self, value) - Property target used to set the boundaries tuple.

### graftPoint Default image-wide graft point (see addEntry for details). Get Method: _getGraftPoint(self) - Property target used to get the graft point. Set Method: _setGraftPoint(self, value) - Property target used to set the graft point.

### useRockRidge Indicates whether to use RockRidge (default is `True`). Get Method: _getUseRockRidge(self) - Property target used to get the use RockRidge flag. Set Method: _setUseRockRidge(self, value) - Property target used to set the use RockRidge flag.

### applicationId Optionally specifies the ISO header application id value. Get Method: _getApplicationId(self) - Property target used to get the application id. Set Method: _setApplicationId(self, value) - Property target used to set the application id.

### biblioFile Optionally specifies the ISO bibliographic file name. Get Method: _getBiblioFile(self) - Property target used to get the biblio file. Set Method: _setBiblioFile(self, value) - Property target used to set the biblio file.

### publisherId Optionally specifies the ISO header publisher id value. Get Method: _getPublisherId(self) - Property target used to get the publisher id. Set Method: _setPublisherId(self, value) - Property target used to set the publisher id.

### preparerId Optionally specifies the ISO header preparer id value. Get Method: _getPreparerId(self) - Property target used to get the preparer id. Set Method: _setPreparerId(self, value) - Property target used to set the preparer id.

### volumeId Optionally specifies the ISO header volume id value. Get Method: _getVolumeId(self) - Property target used to get the volume id. Set Method: _setVolumeId(self, value) - Property target used to set the volume id.