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:
1
2
3
4
5
6
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:
1
2
3
4
import cbmdisk

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

Print MD5 hashes of every file on a disk image:
1
2
3
4
5
6
7
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