rubicon.objc.types — Non-Objective-C types and utilities

This module contains definitions for common C constants and types, and utilities for working with C types.

Common C type definitions

These are commonly used C types from various frameworks.

class rubicon.objc.types.c_ptrdiff_t([value])

The ptrdiff_t type from <stddef.h>. Equivalent to c_long on 64-bit systems and c_int on 32-bit systems.

class rubicon.objc.types.NSInteger([value])

The NSInteger type from <objc/NSObjCRuntime.h>. Equivalent to c_long on 64-bit systems and c_int on 32-bit systems.

class rubicon.objc.types.NSUInteger([value])

The NSUInteger type from <objc/NSObjCRuntime.h>. Equivalent to c_ulong on 64-bit systems and c_uint on 32-bit systems.

class rubicon.objc.types.CGFloat([value])

The CGFloat type from <CoreGraphics/CGBase.h>. Equivalent to c_double on 64-bit systems and c_float on 32-bit systems.

class rubicon.objc.types.NSPoint([x, y])

The NSPoint structure from <Foundation/NSGeometry.h>.

Note

On 64-bit systems this is an alias for CGPoint.

x
y

The X and Y coordinates as CGFloats.

class rubicon.objc.types.CGPoint([x, y])

The CGPoint structure from <CoreGraphics/CGGeometry.h>.

x
y

The X and Y coordinates as CGFloats.

class rubicon.objc.types.NSSize([width, height])

The NSSize structure from <Foundation/NSGeometry.h>.

Note

On 64-bit systems this is an alias for CGSize.

width
height

The width and height as CGFloats.

class rubicon.objc.types.CGSize([width, height])

The CGSize structure from <CoreGraphics/CGGeometry.h>.

width
height

The width and height as CGFloats.

class rubicon.objc.types.NSRect([origin, size])

The NSRect structure from <Foundation/NSGeometry.h>.

Note

On 64-bit systems this is an alias for CGRect.

origin

The origin as a NSPoint.

size

The size as a NSSize.

class rubicon.objc.types.CGRect([origin, size])

The CGRect structure from <CoreGraphics/CGGeometry.h>.

origin

The origin as a CGPoint.

size

The size as a CGSize.

class rubicon.objc.types.UIEdgeInsets([top, left, bottom, right])

The UIEdgeInsets structure from <UIKit/UIGeometry.h>.

top
left
bottom
right

The insets as CGFloats.

class rubicon.objc.types.NSEdgeInsets([top, left, bottom, right])

The NSEdgeInsets structure from <Foundation/NSGeometry.h>.

top
left
bottom
right

The insets as CGFloats.

class rubicon.objc.types.NSTimeInterval([value])

The NSTimeInterval type from <Foundation/NSDate.h>. Equivalent to c_double.

class rubicon.objc.types.CFIndex([value])

The CFIndex type from <CoreFoundation/CFBase.h>. Equivalent to c_longlong on 64-bit systems and c_long on 32-bit systems.

class rubicon.objc.types.UniChar([value])

The UniChar type from <MacTypes.h>. Equivalent to c_ushort.

class rubicon.objc.types.unichar([value])

The unichar type from <Foundation/NSString.h>. Equivalent to c_ushort.

class rubicon.objc.types.CGGlyph([value])

The CGGlyph type from <CoreGraphics/CGFont.h>. Equivalent to c_ushort.

class rubicon.objc.types.CFRange([location, length])

The CFRange type from <CoreFoundation/CFBase.h>.

location
length

The location and length as CFIndexes.

class rubicon.objc.types.NSRange([location, length])

The NSRange type from <Foundation/NSRange.h>.

location
length

The location and length as NSUIntegers.

Common C constants

These are commonly used C constants from various frameworks.

rubicon.objc.types.UIEdgeInsetsZero

The constant UIEdgeInsetsZero: a UIEdgeInsets instance with all insets set to zero.

rubicon.objc.types.NSZeroPoint

The constant NSZeroPoint: a NSPoint instance with the X and Y coordinates set to zero.

rubicon.objc.types.NSIntegerMax

The macro constant NSIntegerMax from <objc/NSObjCRuntime.h>: the maximum value that a NSInteger can hold.

rubicon.objc.types.NSNotFound

The constant NSNotFound from <Foundation/NSObjCRuntime.h>: a NSInteger sentinel value indicating that an item was not found (usually when searching in a collection).

Architecture detection constants

The following constants provide information about the architecture of the current environment. All of them are equivalent to the C compiler macros of the same names.

rubicon.objc.types.__LP64__

Indicates whether the current environment is 64-bit. If true, C longs and pointers are 64 bits in size, otherwise 32 bits.

rubicon.objc.types.__i386__
rubicon.objc.types.__x86_64__
rubicon.objc.types.__arm__
rubicon.objc.types.__arm64__

Each of these constants is true if the current environment uses the named architecture. At most one of these constants is true at once in a single Python runtime. (If the current architecture cannot be determined, all of these constants are false.)

Objective-C type encoding conversion

These functions are used to convert Objective-C type encoding strings to and from ctypes types, and to manage custom conversions in both directions.

All Objective-C encoding strings are represented as bytes rather than str.

rubicon.objc.types.ctype_for_encoding(encoding)

Return the ctype corresponding to an Objective-C type encoding.

If a ctype has been registered for the encoding, that type is returned. Otherwise, if the type encoding represents a compound type (pointer, array, structure, or union), the contained types are converted recursively. A new ctype is then created from the converted ctypes, and is registered for the encoding (so that future conversions of the same encoding return the same ctype).

For example, the type encoding {spam=ic} is not registered by default. However, the contained types i and c are registered, so they are converted individually and used to create a new Structure with two fields of the correct types. The new structure type is then registered for the original encoding {spam=ic} and returned.

Raises

ValueError – if the conversion fails at any point

rubicon.objc.types.encoding_for_ctype(ctype)

Return the Objective-C type encoding for the given ctypes type.

If a type encoding has been registered for the ctype, that encoding is returned. Otherwise, if the ctype is a pointer type, its pointed-to type is encoded and used to construct the pointer type encoding.

Automatic encoding of other compound types (arrays, structures, and unions) is currently not supported. To encode such types, a type encoding must be manually provided for them using register_preferred_encoding() or register_encoding().

Raises

ValueError – if the conversion fails at any point

rubicon.objc.types.register_preferred_encoding(encoding, ctype)

Register a preferred conversion between an Objective-C type encoding and a ctype.

“Preferred” means that any existing conversions in each direction are overwritten with the new conversion. To register an encoding without overwriting existing conversions, use register_encoding().

rubicon.objc.types.with_preferred_encoding(encoding)

Register a preferred conversion between an Objective-C type encoding and the decorated ctype.

This is equivalent to calling register_preferred_encoding() on the decorated ctype.

rubicon.objc.types.register_encoding(encoding, ctype)

Register an additional conversion between an Objective-C type encoding and a ctype.

“Additional” means that any existing conversions in either direction are not overwritten with the new conversion. To register an encoding and overwrite existing conversions, use register_preferred_encoding().

rubicon.objc.types.with_encoding(encoding)

Register an additional conversion between an Objective-C type encoding and the decorated ctype.

This is equivalent to calling register_encoding() on the decorated ctype.

rubicon.objc.types.unregister_encoding(encoding)

Unregister the conversion from an Objective-C type encoding to its corresponding ctype.

Note that this does not remove any conversions in the other direction (from a ctype to this encoding). These conversions may be replaced with register_encoding(), or unregistered with unregister_ctype(). To remove all ctypes for an encoding, use unregister_encoding_all().

If the encoding was not registered previously, nothing happens.

rubicon.objc.types.unregister_encoding_all(encoding)

Unregister all conversions between an Objective-C type encoding and all corresponding ctypes.

All conversions from any ctype to this encoding are removed recursively using unregister_ctype_all().

If the encoding was not registered previously, nothing happens.

rubicon.objc.types.unregister_ctype(ctype)

Unregister the conversion from a ctype to its corresponding Objective-C type encoding.

Note that this does not remove any conversions in the other direction (from an encoding to this ctype). These conversions may be replaced with register_encoding(), or unregistered with unregister_encoding(). To remove all encodings for a ctype, use unregister_ctype_all().

If the ctype was not registered previously, nothing happens.

rubicon.objc.types.unregister_ctype_all(ctype)

Unregister all conversions between a ctype and all corresponding Objective-C type encodings.

All conversions from any type encoding to this ctype are removed recursively using unregister_encoding_all().

If the ctype was not registered previously, nothing happens.

rubicon.objc.types.get_ctype_for_encoding_map()

Get a copy of all currently registered encoding-to-ctype conversions as a map.

rubicon.objc.types.get_encoding_for_ctype_map()

Get a copy of all currently registered ctype-to-encoding conversions as a map.

rubicon.objc.types.split_method_encoding(encoding)

Split a method signature encoding into a sequence of type encodings.

The first type encoding represents the return type, all remaining type encodings represent the argument types.

If there are any numbers after a type encoding, they are ignored. On PowerPC, these numbers indicated each argument/return value’s offset on the stack. These numbers are meaningless on modern architectures.

rubicon.objc.types.ctypes_for_method_encoding(encoding)

Convert a method signature encoding into a sequence of ctypes.

This is equivalent to first splitting the method signature encoding using split_method_encoding(), and then converting each individual type encoding using ctype_for_encoding().

Default registered type encodings

The following table lists Objective-C’s standard type encodings for primitive types, and the corresponding registered ctypes. These mappings can be considered stable, but nonetheless users should not hardcode these encodings unless necessary. Instead, the encoding_for_ctype() function should be used to encode types, because it is less error-prone and more readable than typing encodings out by hand.

Ctype

Type encoding

Notes

None (void)

v

c_bool

B

This refers to the bool type from C99 and C++. It is not necessarily the same as the BOOL type, which may be either c_byte or c_bool depending on the system and architecture.

c_byte

c

c_ubyte

C

c_short

s

c_ushort

S

c_long

l

c_ulong

L

c_int

i

On 32-bit systems, c_int is an alias for c_long, and will be encoded as such.

c_uint

I

On 32-bit systems, c_uint is an alias for c_ulong, and will be encoded as such.

c_longlong

q

On 64-bit systems, c_longlong is an alias for c_long, and will be encoded as such.

c_ulonglong

Q

On 64-bit systems, c_ulonglong is an alias for c_ulong, and will be encoded as such.

c_float

f

c_double

d

c_longdouble

D

On ARM, c_longdouble is an alias for c_double, and will be encoded as such.

c_char

c

Only when encoding. Decoding c produces c_byte, to allow using signed char as a boolean value.

c_char_p

*

POINTER(c_char)

*

Only when encoding. Decoding * produces c_char_p for easier use of C strings.

POINTER(c_byte)

*

Only when encoding. Decoding * produces c_char_p for easier use of C strings.

POINTER(c_ubyte)

*

Only when encoding. Decoding * produces c_char_p for easier use of C strings.

c_wchar

i

Only when encoding. Decoding i produces c_int.

c_wchar_p

^i

Only when encoding. Decoding ^i produces POINTER(c_int).

c_void_p

^v

UnknownPointer

^?

This encoding stands for a pointer to a type that cannot be encoded, which in practice means a function pointer.

UnknownPointer

^{?}, ^(?)

Only when decoding. These encodings stand for pointers to a structure or union with unknown name and fields.

objc_id

@

Class name suffixes in the encoding (e. g. @"NSString") are ignored.

objc_block

@?

Block signature suffixes in the encoding (e. g. @?<v@?>) are ignored.

SEL

:

Class

#

class rubicon.objc.types.UnknownPointer(value=None)

Placeholder for the “unknown pointer” types ^?, ^{?} and ^(?).

Not to be confused with a ^v void pointer.

Usually a ^? is a function pointer, but because the encoding doesn’t contain the function signature, you need to manually create a CFUNCTYPE with the proper types, and cast this pointer to it.

^{?} and ^(?) are pointers to a structure or union (respectively) with unknown name and fields. Such a type also cannot be used meaningfully without casting it to the correct pointer type first.

In addition, the following types defined by Rubicon are registered, but their encodings may vary depending on the system and architecture:

Conversion of Python sequences to C structures and arrays

This function is used to convert a Python sequence (such as a tuple or list) to a specific C structure or array type. This function is mainly used internally by Rubicon, to allow passing Python sequences as method parameters where a C structure or array would normally be required. Most users will not need to use this function directly.

rubicon.objc.types.compound_value_for_sequence(seq, tp)

Create a C structure or array of type tp, initialized with values from seq.

If tp is a Structure type, the newly created structure’s fields are initialized in declaration order with the values from seq. seq must have as many elements as the structure has fields.

If tp is a Array type, the newly created array is initialized with the values from seq. seq must have as many elements as the array type.

In both cases, if a structure field type or the array element type is itself a structure or array type, the corresponding value from seq is recursively converted as well.

Python to ctypes type mapping

These functions are used to map Python types to equivalent ctypes types, and to add or remove such mappings. This mechanism is mainly used internally by Rubicon, to for example allow ObjCInstance to be used instead of objc_id in method type annotations. Most users will not need to use these functions directly.

rubicon.objc.types.ctype_for_type(tp)

Look up the ctype corresponding to the given Python type.

This conversion is applied to types used in objc_method signatures, objc_ivar types, etc. This function translates Python built-in types and rubicon.objc classes to their ctypes equivalents. Unregistered types (including types that are already ctypes) are returned unchanged.

rubicon.objc.types.register_ctype_for_type(tp, ctype)

Register a conversion from a Python type to a ctype.

rubicon.objc.types.unregister_ctype_for_type(tp)

Unregister a conversion from a Python type to a ctype.

rubicon.objc.types.get_ctype_for_type_map()

Get a copy of all currently registered type-to-ctype conversions as a mapping.

Default registered mappings

The following mappings are registered by default by Rubicon.

Python type

Ctype

int

c_int

float

c_float

bool

c_bool

bytes

c_char_p

ObjCInstance

objc_id

ObjCClass

Class