`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 C type corresponding to an Objective-C type encoding.

If a C type 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 C type is then created from the converted ctypes, and is registered for the encoding (so that future conversions of the same encoding return the same C type).

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 C type, that encoding is returned. Otherwise, if the C type 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)#

“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)#

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

rubicon.objc.types.register_encoding(encoding, 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)#

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

rubicon.objc.types.unregister_encoding(encoding)#

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

Note that this does not remove any conversions in the other direction (from a C type 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 C type 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 C type to its corresponding Objective-C type encoding.

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

If the C type was not registered previously, nothing happens.

rubicon.objc.types.unregister_ctype_all(ctype)#

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

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

If the C type was not registered previously, nothing happens.

rubicon.objc.types.get_ctype_for_encoding_map()#: Get a copy of all currently registered encoding-to-C type conversions as a map.

rubicon.objc.types.get_encoding_for_ctype_map()#: Get a copy of all currently registered C type-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 hard code 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:

ctypes.py_object
NSInteger
NSUInteger
CGFloat
NSPoint
CGPoint
NSSize
CGSize
NSRect

CGRect
UIEdgeInsets
NSEdgeInsets
NSTimeInterval
CFIndex
UniChar
unichar
CGGlyph
NSRange

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 C type 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 C type.

rubicon.objc.types.unregister_ctype_for_type(tp)#: Unregister a conversion from a Python type to a C type.

rubicon.objc.types.get_ctype_for_type_map()#: Get a copy of all currently registered type-to-C type 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`

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

Common C type definitions#

Common C constants#

Architecture detection constants#

Objective-C type encoding conversion#

Default registered type encodings#

Conversion of Python sequences to C structures and arrays#

Python to ctypes type mapping#

Default registered mappings#

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

Python to `ctypes` type mapping#