Examples
The easiest way to learn PyCdlib is to see some examples. Before getting to the examples, we first start out with the PyCdlib theory of operation.
PyCdlib theory of operation
PyCdlib aims to allow users to manipulate ISOs in arbitrary ways, from creating new ISOs to modifying and writing out existing ISOs. Along the way, the PyCdlib API is meant to hide the details of the above standards, letting users concentrate on the modifications they wish to make.
To start using the PyCdlib API, the user must create a new PyCdlib object. A PyCdlib object cannot do very much until it is initialized, either by creating a new ISO (using the new method), or by opening an existing ISO (using the open method). Once a PyCdlib object is initialized, files can be added or removed, directories can be added or removed, the ISO can be made bootable, and various other manipulations of the ISO can happen. Once the user is happy with the current layout of the ISO, the write method can be called, which will write out the current state of the ISO to a file (or file-like object).
Due to some historical aspects of the ISO standards, making modifications to an existing ISO can involve shuffling around a lot of metadata. In order to maintain decent performance, PyCdlib takes a “lazy” approach to updating that metadata, and only does the update when it needs the results. This allows the user to make several modifications and effectively “batch” operations without significantly impacting speed. The minor downside to this is that the metadata stored in the PyCdlib object is not always consistent, so if the user wants to reach into the object to look at a particular field, it may not always be up-to-date. PyCdlib offers a force_consistency API that immediately updates all metadata for just this reason.
Facades
The base PyCdlib object hides many of the details of the ISO and related standards, but still has some complexity to allow arbitrary modifications to be made. The “facades”, on the other hand, sacrifice some of this flexibility for an even simpler interface that allows the user to operate in just one of the contexts. The benefit is that the user can just work in the context they prefer, and the facade will handle the details of compatibility with the other contexts. The downside is that making modifications via the facades only modifies the context that the facade is for, leaving it out of the other contexts. For instance, if the “PyCdlibJoliet” facade is being used, and a file is added via “add_fp”, then that file will only show up in the Joliet context. This means that it won’t be visible by default to Unix operating systems (which generally prefer to use the Rock Ridge context).
Example format
We’ll start out each example with the entire source code needed to run the example, and then break down the code to show what the individual pieces do. Note that in most cases, error handling is elided for brevity, though it probably shouldn’t be in real code.
- Creating a new, basic ISO
- Opening an existing ISO
- Extracting data from an existing ISO
- Creating a bootable ISO (El Torito)
- Creating an ISO with Rock Ridge
- Creating an ISO with Joliet
- Creating an ISO with UDF
- Using a facade
- Modifying a file in place
- Managing hard-links on an ISO
- Forcing consistency
- Creating a “hybrid” bootable ISO
- Walking the ISO filesystem
- Reading a large file in chunks