CBMdisk: A DirMaster Python wrapper¶

CBMdisk is an API/wrapper around the DirMaster backend engine. It allows one to produce Python based scripts and applications that can open, manipulate, and save the same Commodore disk, file and archiver formats that are supported by the DirMaster application itself. Many other features of DirMaster like exporting picture file formats (e.g. koala to .png), SEQ files (e.g. to .txt), disk directories (e.g. to .html) and so on are also exposed by the API.

Examples¶

Produce a new disk image with a file copied from the OS:

import cbmdisk

disk = cbmdisk.Disk(type='D64')
disk.files.insert(0, "fixmydemo.prg")
print disk.free_blocks
disk.save("release.d64")

Save a disk image directory as a .png image:

import cbmdisk

disk = cbmdisk.Disk("disk.d81")
disk.save("disk.png")

Print MD5 hashes of every file on a disk image:

import cbmdisk, hashlib

disk = cbmdisk.Disk("disk.nib")
for file in disk.files:
  md5 = hashlib.md5()
  md5.update(file.bytes)
  print file.name, md5.hexdigest()

Contents:¶

Disk¶

class cbmdisk.Disk(filename=None, type=None)¶

Parameters:

filename (integer or None) – If specified, will atempt to load this file, and type parameter will be ignored. Disk type will be based on the file extension.
type (integer or None) – String specifying type of disk to be created. For example “d64” or “d81”
size (integer or None) – Size of the disk in sectors, for the disks that are variable size. Such as DNP.
fill_byte (byte or None) – Byte to use to fill empty sectors, otherwise the default fill byte of 1 would be used, except for the second byte of each sector.

bam_track_sector¶: Returns the track and sector of the bam as a tuple.

compact()¶: Compacts the disk directory, removing splat files.

create_side_sectors(track, sector, record_length)¶

Generates a side sector file based on the track and sector of a file, and the record length. A (track, sector) tuple is returned pointing to the head of the side sector.

Parameters:	record_length (integer) – The length of each record.

custom_interleave¶: Custom interleave value.

dir_track_sector¶: Returns the track and sector of the directory as a tuple.

hide_splat_files¶: If set to true includes DEL, splatted files in the list of files.

files¶: Files iterator. (read only)

fill_free_sectors(fill_byte)¶: Fills the empty sectors with fill_byte.

free_blocks¶: Count of free blocks. (read only)

get_rel_record(track, sector, record_length, record_index)¶

Gets a single record from a REL file.

Parameters:	record_length (integer) – Length of each record. record_index (integer) – Index of record to return
Return type:	binary string

get_sector_bytes(track, sector)¶

Returns the bytes of a sector in a binary string.

Return type:	binary string of length 256 bytes

get_sector_count(track)¶: Returns the number of sectors for the given track.

get_sector_error(track, sector)¶

Returns the error for track,sector.

Return type:	integer

id¶: Disk ID. Binary string, only the first 5 characters will be used.

interleave_progressive¶: If true, will start free sectors at track 1, sector 0 and will increment by one sector. If false will use the appropriate interleave algorithm for the disk type.

is_extendable¶: Bool indicating if the disk can be extended.

is_extended¶: Extend a 1541 disk to 40 tracks.

is_geos¶: Returns true if the disk is marked as a GEOS disk. (read only)

is_sector_bam(track, sector)¶: Returns true if the track,sector is a BAM sector.

is_sector_free(track, sector)¶: Returns true if the track,sector is free.

is_sector_valid(track, sector)¶: Returns true if the track and sector is valid.

mark_as_geos(filename=None, type=None)¶: Marks the disk as a GEOS disk.

name¶: Disk name in PETSCII.

next_dir_sector(sector=sector)¶: If sector isn’t specified, will return what should be the first directory sector. Otherwise returns what should be the next directory sector for the given sector. Used internally to figure out what the next new disk directory should be.

next_free_sector(track, sector)¶: Returns the next free sector as a (track,sector) tuple. Sector isn’t marked as used.

save(filename, selection=None, font=None, recurse=None, display_hash=None, css_link=None, headless_html=None)¶

Saves the disk. Type of disk to be saved is based on the extension in the param filename.

Parameters:

filename (string) – name of file to be saved.
selection (list of integers) – Indexes of “selected” files, these files will be the only ones included in the exported, disk. This selection is ignored for normal disks, such as d64, d81, etc.
font (dict) – a font dictionary describing the font.
recurse (bool) – Recurses into OS subdirectories for non disk saves.
display_hash (bool) – Includes the file hash if saving as a .csv.
css_link (string) – If specified, will use this as a css link when saving as html.
headless_html (bool) – If true, will save only the html, when saving as html, if false saves the css as well

set_sector_bytes(track, sector, bytes)¶

Sets the binary string at track, sector.

Parameters:	bytes – The bytes to set into the sector. The bytes are copied into the sector starting with the first byte of the sector, up to the first 256 bytes of the string.

set_sector_error(track, sector, error)¶

Sets the error for track,sector.

Parameters:	error (integer) – Error number.

set_sector_free(track, sector, free=True)¶: Marks the sector as free if free is true, otherwise marks it as used.

size¶: Size of disk in bytes. (read only)

supports_sub_dir¶: Returns true if this disk supports sub directories. (read only)

type¶: Disk type (read only)

types¶: Returns list of file types supported by this disk.

validate()¶: Validates the disk

Files¶

class cbmdisk.Files¶

An iterator that represents the directory on the disk.

copy(file_index, :py:class:`File`)¶

Copies File before file_index. If File is on the same disk, this will create a duplicate.

Parameters:	file_index (integer) – New `File` is inserted before this index. Use len( `Disk.files()` ) to append to end. file (File) – `File` to copy.

create(file_index)¶

Creates a file entry before file_index.

Parameters:	file_index (integer) – New filename is inserted before this index. Use Files.length to append to end.
Return type:	`File`

create_partition(file_index, size=None, type=None)¶

Create a parition or subdirectory before file_index. Returns a File. Use File.disk() to retrieve the partition or sub directory.

Parameters:	file_index (integer) – creates partition before file_index. size (integer) – size of CBM sub directory. This can only be used on a D81, other disk types will ignore. type (string) – Type of parition on a D2M disk, other disk types will ignore. Possible types are “d64”, “d81”, “dnp”
Return type:	`File`

delete(file_index)¶

Marks the file as deleted, and frees the BAM.

Parameters:	file_index (integer) – File to delete, should be less than len(`Files`)

find(petscii_name)¶

Returns the File with the name if it exists, or None.

Parameters:	petscii_name (string) – PETSCII name of file to find
Return type:	`File`

insert(file_index, filename)¶

Inserts the given OS file before file_index.

Parameters:	file_index (integer) – New file is inserted before this index. Use len(Files) to append to end. filename (string) – Name of OS file, for example “c:c64file.prg”

move(source_file_index, destination_file_index)¶

Moves the file at source_file_index to before destination_file_index.

Parameters:	source_file_index (integer) – File to copy, should be less than Files.length destination_file_index (integer) – New file is moved before this index. Use Files.length to append to end.
Return type:	`File`

sort(reverse=False, size=False)¶

Sorts the files by name or by size.

Parameters:	reverse (bool) – Reverse the sort order if set. size (bool) – If true, sorts by size. Default is to sort on name

File¶

class cbmdisk.File¶

bytes¶: Binary string representing the file.

chain¶: List of (track,sector) tuples representing the file chain.

description¶: Description of the file, based on what the autoview things. For example “BASIC”, or “Koala”. (read only)

disk¶: Disk the file is on. This may be different if the original disk has partitions. (read only)

files¶: Files iterator if this is a parition or sub directory, otherwise is None.

geos_author¶: Returns an ASCII string of the author field.

geos_class¶: Returns an ASCII string of the class field.

geos_description¶: Returns an ASCII string of the description field.

geos_end_address¶: File End address.

geos_filestruct¶: Geos filestruct.

geos_load_address¶: File load address.

geos_start_address¶: File start address.

geos_type¶: Geos file type.

index¶: Index of the file on the directory. (read only)

is_compressed¶: True if file is compressed. (read only)

is_geos¶: True if the file is a GEOS file.

lock¶: True if the file is locked.

name¶: PETSCII name of the file.

record_length¶: Record Length of the REL file.

save(name, font=None, scale=1, x2=False, csslink=None, headless=None)¶

Exports the file to disk.

Parameters:

name (string) – (required) file name to be saved to. Extention is the type of file to be saved.
font (font) – Font namedtuple, describing the font.
scale (float) – Float value to scale images.
x2 (bool) – displays font as a 2x2 font, instead of a 1x1. Only used if the file is a font and is being output as an image.
csslink (string) – If set uses this as the css link for html, otherwise the css is embedded in the html.
headless (bool) – if true won’t include the HTML headers, and will output just the html body.

sector¶: Sector of the file.

side_sector¶: Side sector of the file.

side_track¶: Side track of the file.

size¶: File size as reported in the directory.

splat¶: True if it is a splat file.

time¶: Returns a DateTime object of the GEOS time.

track¶: Track of the file.

type¶: File type “PRG”, “SEQ”, “USR”, “DEL”, etc.

uncompress()¶: Returns a tuple. The first item is cbmdisk.Disk if the file can be uncompressed. The second item is a PETSCII representation of the “title” track, if it was present. Will throw an cbmdisk error if unable to decompress the file.

Misc Functions¶

cbmdisk.extensions¶: Returns a list of supported extensions.

cbmdisk.palette(filename=None)¶

Loads a color palette. Specifying None will revert to the default palette.

Parameters:	filename (string) – Name of a VICE Palette file to load.

cbmdisk.to_ascii(string[, upper=True])¶

Converts the string to ASCII.

Parameters:	string (string) – Binary string to convert to ASCII. upper (bool) – If true uses the uppercase font, otherwise uses the upper/lowercase font.
Return type:	ASCII representation of string.

cbmdisk.to_petscii(string[, upper=True])¶

Converts the string to PETSCII.

Parameters:	string (string) – ASCII string to convert to PETSCII. upper (bool) – If true uses the uppercase font, otherwise uses the upper/lowercase font.
Return type:	PETSCII representation of string.

cbmdisk.to_unicode(string[, upper=True, ctrlchrs=True])¶

Converts the string to Unicode.

Parameters:	string (string) – PETSCII to convert to Unicode. upper (bool) – If true uses the uppercase font, otherwise uses the upper/lowercase font. ctrlchrs (bool) – If true shows control characters as reversed images. Characters < $20 and between $80 and $a0
Return type:	Unicode representation of string.

cbmdisk.__versions__¶: Returns the version number of cbmdisk.

Exception¶

exception cbmdisk.error¶: Generic cbmdisk error exception.

exception cbmdisk.full¶: Disk full error.

Data Structure¶

cbmdisk.font(size, upper, text, bg)¶

Parameters:	size (integer) – Point size, Default is 8. upper (bool) – True for upper case font, false for upper/lower. Default is True. text (string) – Text color. Default is 14, the index to light blue. bg (string) – Background color. Default is 6, the index to blue.

If color is an int less than 16, it refers to and index into the palette. If color starts with a ‘#’ then what follows will be the RGB values in hex Color can be a color name. If it matches a CBM color name, the appropriate index will be used. Finally if the color matches a wxWidget color, then the RGB value will be used.

Index Color

0 Black

1 White

2 Red

3 Cyan

4 Purple

5 Green

6 Blue

7 Yellow

8 Orange

9 Brown

10 Lt Red

11 Dark Grey

12 Med Grey

13 Lt Green

14 Lt Blue

15 Lt Grey

Index	Color
0	Black
1	White
2	Red
3	Cyan
4	Purple
5	Green
6	Blue
7	Yellow
8	Orange
9	Brown
10	Lt Red
11	Dark Grey
12	Med Grey
13	Lt Green
14	Lt Blue
15	Lt Grey