# eric6.Utilities.binplistlib

Module implementing a library for reading and writing binary property list files.

Binary Property List (plist) files provide a faster and smaller serialization format for property lists on OS X. This is a library for generating binary plists which can be read by OS X, iOS, or other clients.

The API models the plistlib API, and will call through to plistlib when XML serialization or deserialization is required.

To generate plists with UID values, wrap the values with the Uid object. The value must be an int.

To generate plists with NSData/CFData values, wrap the values with the Data object. The value must be a bytes object.

Date values can only be datetime.datetime objects.

The exceptions InvalidPlistException and NotBinaryPlistException may be thrown to indicate that the data cannot be serialized or deserialized as a binary plist.

Plist generation example:

        from binplistlib import *
        from datetime import datetime
        plist = {'aKey':'aValue',
                 '0':1.322,
                 'now':datetime.now(),
                 'list':[1,2,3],
                 'tuple':('a','b','c')
                 }
        try:
            writePlist(plist, "example.plist")
        except (InvalidPlistException, NotBinaryPlistException) as e:
            print("Something bad happened:", e)

Plist parsing example:

        from binplistlib import *
        try:
            plist = readPlist("example.plist")
            print(plist)
        except (InvalidPlistException, NotBinaryPlistException) as e:
            print("Not a plist:", e)

### Global Attributes

PlistByteCounts
PlistTrailer
__all__
apple_reference_date_offset

### Classes

BoolWrapper | Class wrapping a boolean value.
Data | Class implementing a wrapper around bytes types for representing Data values.
HashableWrapper | Class wrapping a hashable value.
InvalidPlistException | Exception raised when the plist is incorrectly formatted.
NotBinaryPlistException | Exception raised when a binary plist was expected but not encountered.
PlistReader | Class implementing the plist reader.
PlistWriter | Class implementing the plist writer.
Uid | Class implementing a wrapper around integers for representing UID values.

### Functions

is_stream_binary_plist | Module function to check, if the stream is a binary plist.
readPlist | Module function to read a plist file.
readPlistFromBytes | Module function to read from a plist bytes object.
writePlist | Module function to write a plist file.
writePlistToBytes | Module function to write a plist bytes object.

## BoolWrapper

Class wrapping a boolean value.

### Derived from

object

### Class Attributes

None

### Class Methods

None

### Methods

BoolWrapper | Constructor
__repr__ | Special method to generate a representation of the object.

### Static Methods

None

#### BoolWrapper (Constructor)

BoolWrapper(value)

Constructor

value
  object value (boolean)

#### BoolWrapper.__repr__

__repr__()

Special method to generate a representation of the object.

Returns:
  object representation (string)

Up

## Data

Class implementing a wrapper around bytes types for representing Data values.

### Derived from

bytes

### Class Attributes

None

### Class Methods

None

### Methods

None

### Static Methods

None

Up

## HashableWrapper

Class wrapping a hashable value.

### Derived from

object

### Class Attributes

None

### Class Methods

None

### Methods

HashableWrapper | Constructor
__repr__ | Special method to generate a representation of the object.

### Static Methods

None

#### HashableWrapper (Constructor)

HashableWrapper(value)

Constructor

value
  object value

#### HashableWrapper.__repr__

__repr__()

Special method to generate a representation of the object.

Returns:
  object representation (string)

Up

## InvalidPlistException

Exception raised when the plist is incorrectly formatted.

### Derived from

Exception

### Class Attributes

None

### Class Methods

None

### Methods

None

### Static Methods

None

Up

## NotBinaryPlistException

Exception raised when a binary plist was expected but not encountered.

### Derived from

Exception

### Class Attributes

None

### Class Methods

None

### Methods

None

### Static Methods

None

Up

## PlistReader

Class implementing the plist reader.

### Derived from

object

### Class Attributes

contents
currentOffset
file
offsets
trailer

### Class Methods

None

### Methods

PlistReader | Constructor
getSizedInteger | Public method to read an integer of a specific size.
parse | Public method to parse the plist data.
proc_extra |
readArray | Public method to read an Array object.
readAsciiString | Public method to read an ASCII encoded string.
readData | Public method to read some bytes.
readDate | Public method to read a date.
readDict | Public method to read a Dictionary object.
readInteger | Public method to read an Integer object.
readObject | Public method to read the object data.
readReal | Public method to read a Real object.
readRefs | Public method to read References.
readRoot | Public method to read the root object.
readUid | Public method to read a UID.
readUnicode | Public method to read an Unicode encoded string.
reset | Public method to reset the instance object.
setCurrentOffsetToObjectNumber | Public method to set the current offset.

### Static Methods

None

#### PlistReader (Constructor)

PlistReader(fileOrStream)

Constructor

fileOrStream
  open file containing the plist data (file object)

#### PlistReader.getSizedInteger

getSizedInteger(data, length)

Public method to read an integer of a specific size.

data
  data to extract the integer from (bytes)
length
  length of the integer (integer)

Returns:
  read integer (integer)

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistReader.parse

parse()

Public method to parse the plist data.

Returns:
  unpickled object

#### PlistReader.proc_extra

proc_extra()

#### PlistReader.readArray

readArray(count)

Public method to read an Array object.

count
  number of array elements (integer)

Returns:
  list of unpickled objects

#### PlistReader.readAsciiString

readAsciiString(length)

Public method to read an ASCII encoded string.

length
  length of the string (integer)

Returns:
  ASCII encoded string

#### PlistReader.readData

readData(length)

Public method to read some bytes.

length
  number of bytes to read (integer)

Returns:
  Data object

#### PlistReader.readDate

readDate()

Public method to read a date.

Returns:
  date object (datetime.datetime)

#### PlistReader.readDict

readDict(count)

Public method to read a Dictionary object.

count
  number of dictionary elements (integer)

Returns:
  dictionary of unpickled objects

#### PlistReader.readInteger

readInteger(length)

Public method to read an Integer object.

length
  length of the object (integer)

Returns:
  integer object

#### PlistReader.readObject

readObject()

Public method to read the object data.

Returns:
  unpickled object

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistReader.readReal

readReal(length)

Public method to read a Real object.

length
  length of the object (integer)

Returns:
  float object

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistReader.readRefs

readRefs(count)

Public method to read References.

count
  amount of the references (integer)

Returns:
  list of references (list of integers)

#### PlistReader.readRoot

readRoot()

Public method to read the root object.

Returns:
  unpickled object

Raises InvalidPlistException:
  raised to indicate an invalid plist file
Raises NotBinaryPlistException:
  raised to indicate, that the plist file is not a binary file

#### PlistReader.readUid

readUid(length)

Public method to read a UID.

length
  length of the UID (integer)

Returns:
  Uid object

#### PlistReader.readUnicode

readUnicode(length)

Public method to read an Unicode encoded string.

length
  length of the string (integer)

Returns:
  unicode encoded string

#### PlistReader.reset

reset()

Public method to reset the instance object.

#### PlistReader.setCurrentOffsetToObjectNumber

setCurrentOffsetToObjectNumber(objectNumber)

Public method to set the current offset.

objectNumber
  number of the object (integer)

Up

## PlistWriter

Class implementing the plist writer.

### Derived from

object

### Class Attributes

byteCounts
computedUniques
file
header
referencePositions
trailer
wrappedFalse
wrappedTrue
writtenReferences

### Class Methods

None

### Methods

PlistWriter | Constructor
__checkKey | Private method to check the validity of a key.
__processSize | Private method to process a size.
binaryInt | Public method to pack an integer object.
binaryReal | Public method to pack a real object.
computeOffsets | Public method to compute offsets of an object.
incrementByteCount | Public method to increment the byte count.
intSize | Public method to determine the number of bytes necessary to store the given integer.
positionOfObjectReference | Public method to get the position of an object.
proc_variable_length |
realSize | Public method to determine the number of bytes necessary to store the given real.
reset | Public method to reset the instance object.
wrapRoot | Public method to generate object wrappers.
writeObject | Public method to serialize the given object to the output.
writeObjectReference | Public method to write an object reference.
writeOffsetTable | Public method to write all of the object reference offsets.
writeRoot | Public method to write an object to a plist file.

### Static Methods

None

#### PlistWriter (Constructor)

PlistWriter(file)

Constructor

file
  file to write the plist data to (file object)

#### PlistWriter.__checkKey

__checkKey(key)

Private method to check the validity of a key.

key
  key to be checked

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistWriter.__processSize

__processSize(size)

Private method to process a size.

size
  size value to be processed (int)

Returns:
  processed size (int)

#### PlistWriter.binaryInt

binaryInt(obj, length=None)

Public method to pack an integer object.

obj
  integer to be packed
length
  length the integer should be packed into (integer)

Returns:
  serialized object (bytes)

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistWriter.binaryReal

binaryReal(obj)

Public method to pack a real object.

obj
  real to be packed

Returns:
  serialized object (bytes)

#### PlistWriter.computeOffsets

computeOffsets(obj, asReference=False, isRoot=False)

Public method to compute offsets of an object.

obj
  plist object
asReference
  flag indicating offsets as references (boolean)
isRoot
  flag indicating a root object (boolean)

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistWriter.incrementByteCount

incrementByteCount(field, incr=1)

Public method to increment the byte count.

field
  field to evaluate
incr
  byte count increment (integer)

#### PlistWriter.intSize

intSize(obj)

Public method to determine the number of bytes necessary to store the given integer.

obj
  integer object

Returns:
  number of bytes required (integer)

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistWriter.positionOfObjectReference

positionOfObjectReference(obj)

Public method to get the position of an object.

If the given object has been written already, return its position in the offset table. Otherwise, return None.

obj
  object

Returns:
  position of the object (integer)

#### PlistWriter.proc_variable_length

proc_variable_length(length)

#### PlistWriter.realSize

realSize(obj)

Public method to determine the number of bytes necessary to store the given real.

obj
  real object

Returns:
  number of bytes required (integer)

#### PlistWriter.reset

reset()

Public method to reset the instance object.

#### PlistWriter.wrapRoot

wrapRoot(root)

Public method to generate object wrappers.

root
  object to be wrapped

Returns:
  wrapped object

#### PlistWriter.writeObject

writeObject(obj, output, setReferencePosition=False)

Public method to serialize the given object to the output.

obj
  object to be serialized
output
  output to be serialized to (bytes)
setReferencePosition
  flag indicating, that the reference position the object was written to shall be recorded (boolean)

Returns:
  new output

#### PlistWriter.writeObjectReference

writeObjectReference(obj, output)

Public method to write an object reference.

Tries to write an object reference, adding it to the references table. Does not write the actual object bytes or set the reference position. Returns a tuple of whether the object was a new reference (True if it was, False if it already was in the reference table) and the new output.

obj
  object to be written
output
  output stream to append the object to

Returns:
  flag indicating a new reference and the new output

#### PlistWriter.writeOffsetTable

writeOffsetTable(output)

Public method to write all of the object reference offsets.

output
  current output (bytes)

Returns:
  new output (bytes)

Raises InvalidPlistException:
  raised to indicate an invalid plist file

#### PlistWriter.writeRoot

writeRoot(root)

Public method to write an object to a plist file.

Strategy is:

- write header
- wrap root object so everything is hashable
- compute size of objects which will be written
  - need to do this in order to know how large the object refs will be in the list/dict/set reference lists
- write objects
  - keep objects in writtenReferences
  - keep positions of object references in referencePositions
  - write object references with the length computed previously
- computer object reference length
- write object reference positions
- write trailer

root
  reference to the object to be written

Up

## Uid

Class implementing a wrapper around integers for representing UID values.

This is used in keyed archiving.

### Derived from

int

### Class Attributes

None

### Class Methods

None

### Methods

__repr__ | Special method to return an object representation.

### Static Methods

None

#### Uid.__repr__

__repr__()

Special method to return an object representation.

Returns:
  object representation (string)

Up

## is_stream_binary_plist

is_stream_binary_plist(stream)

Module function to check, if the stream is a binary plist.

stream
  plist stream (file object)

Returns:
  flag indicating a binary plist (boolean)

Up

## readPlist

readPlist(pathOrFile)

Module function to read a plist file.

pathOrFile
  name of the plist file (string) or an open file (file object)

Returns:
  reference to the read object

Raises InvalidPlistException:
  raised to signal an invalid plist file

Up

## readPlistFromBytes

readPlistFromBytes(data)

Module function to read from a plist bytes object.

data
  plist data (bytes)

Returns:
  reference to the read object

Up

## writePlist

writePlist(rootObject, pathOrFile, binary=True)

Module function to write a plist file.

rootObject
  reference to the object to be written
pathOrFile
  name of the plist file (string) or an open file (file object)
binary
  flag indicating the generation of a binary plist file (boolean)

Up

## writePlistToBytes

writePlistToBytes(rootObject, binary=True)

Module function to write a plist bytes object.

rootObject
  reference to the object to be written
binary
  flag indicating the generation of a binary plist bytes object (boolean)

Returns:
  bytes object containing the plist data

Up