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.
|
__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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
_getDevice(self)
Property target used to get the device value. |
source code
|
|
|
|
|
_getBoundaries(self)
Property target used to get the boundaries value. |
source code
|
|
|
|
|
_getGraftPoint(self)
Property target used to get the graft point. |
source code
|
|
|
|
|
_getUseRockRidge(self)
Property target used to get the use RockRidge flag. |
source code
|
|
|
|
|
_getApplicationId(self)
Property target used to get the application id. |
source code
|
|
|
|
|
_getBiblioFile(self)
Property target used to get the biblio file. |
source code
|
|
|
|
|
_getPublisherId(self)
Property target used to get the publisher id. |
source code
|
|
|
|
|
_getPreparerId(self)
Property target used to get the preparer 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__
|
|
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__
|
__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. :)
|
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
|
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 .
|
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.
|
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
|
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 .
|
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 .
|
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 .
|
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
|
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.
|
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.
|
Property target used to set the use RockRidge flag. No validations,
but we normalize the value to True or
False .
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|