Package pycocoa :: Module nstypes
[frames] | no frames]

Module nstypes

ObjC classes NS... and conversions from NS... ObjC to Python instances.


Version: 25.02.04

Classes
  NSDecimal
Optimized, Python NSDecimalNumber class.
  NSExceptionError
Python Error wrapping an ObjC/NSException.
  NSStr
Python wrapper for the ObjC NS[Constant]String.
  at
Acronym NSStr.
Functions
 
isAlias(path)
Resolve a macOS file or folder alias.
 
isLink(path)
Resolve a file or folder link or alias.
 
isNone(obj)
Return True if obj is None, NSMain.nil, NSMain.Null, etc.
 
nsArray2listuple(ns, ctype=<class 'ctypes.c_void_p'>)
Create a Python list or tuple from an NS[Mutable]Array.
 
nsArray2tuple(ns, ctype=<class 'pycocoa.runtime.ObjCInstance'>)
Create a Python tuple from an immutable NSArray.
 
nsBoolean2bool(ns, dflt=missing)
Create a Python bool from an NSBoolean.
 
nsBundleRename(ns_title, match='Python')
Change the bundle title if the current title matches.
 
nsData2bytes(ns, dflt='')
Create Python bytes from NSData.
 
nsDecimal2decimal(ns)
Create a Python Decimal from an NSDecimal.
 
nsDescription2dict(ns, **defaults)
Create an immutable dict object with key and attribute access to items by name.
 
nsDictionary2dict(ns, ctype_keys=<class 'ctypes.c_void_p'>, ctype_vals=<class 'ctypes.c_void_p'>)
Create a Python dict from an NS[Mutable]Dictionary.
 
nsDictionary2items(ns)
Yield the (key, value) items from an NSDictionary.
 
nsException(name=None, reason='not given', **info)
Create an ObjC/NSException instance.
 
nsIter(ns, reverse=False)
Iterate over an NS.. ObjC objects's (reverse) enumerator.
 
nsIter2(ns, reverse=False)
Iterate over an NS.. ObjC objects's (reverse) enumerator.
 
nsLog(ns_fmt, *ns_args)
Formatted ObjC write to the console.
 
nsLogf(fmtxt, *args)
Formatted write to the console.
 
nsNull2none(ns)
Return Python None for an NS/CFNull or nil.
 
nsNumber2num(ns, dflt=missing)
Create a Python Decimal, int or float from an NSNumber.
 
nsOf(inst)
Return the .NS ObjC object of a Python wrapper or Type instance.
 
nsRaise(name=None, reason='not given', **info)
Create an NSException and mimick @throw NSException.
 
nsSet2set(ns, ctype=<class 'ctypes.c_void_p'>)
Create a Python set or frozenset from an NS[Mutable]Set.
 
nsString2str(ns, dflt=None)
Create a Python str or unicode from an NS[Mutable]Str[ing].
 
nsTextSize3(text, ns_font=None)
Return the size of a multi-line text.
 
nsTextView(text, ns_font)
Return an NSTextView for the given text string.
 
nsThrow(nsExc)
Mimick ObjC's @throw NSException to raise an exception.
 
nsURL2str(ns)
Create a Python str from NSURL string.
 
nsValue2py(ns, dflt=missing)
Create a Python instance from an NS[Concrete]Value.
 
ns2py(ns, dflt=missing)
Convert (an instance of) an ObjC class to an instance of the equivalent Python standard type or wrapper and value.
 
ns2Type(ns)
Convert an NS... ObjC object to an instance of the corresponding Python Type and value.
 
ns2TypeID2(ns, dflt=None)
Get the NS... ObjC TypeID.
Variables
  __all__ = _ALL_LAZY.nstypes
  NSAlert = ObjCClass('NSAlert')
  NSApplication = ObjCClass('NSApplication')
  NSArray = ObjCClass('NSArray')
  NSAttributedString = ObjCClass('NSAttributedString')
  NSAutoreleasePool = ObjCClass('NSAutoreleasePool')
  NSBezierPath = ObjCClass('NSBezierPath')
  NSBundle = ObjCClass('NSBundle')
  NSColor = ObjCClass('NSColor')
  NSConcreteNotification = ObjCClass('NSConcreteNotification')
  NSConcreteValue = ObjCClass('NSConcreteValue')
  NSConstantString = ObjCClass('NSConstantString')
  NSData = ObjCClass('NSData')
  NSDate = ObjCClass('NSDate')
  NSDecimalNumber = ObjCClass('NSDecimalNumber')
  NSDictionary = ObjCClass('NSDictionary')
  NSDockTile = ObjCClass('NSDockTile')
  NSEnumerator = ObjCClass('NSEnumerator')
  NSError = ObjCClass('NSError')
  NSException = ObjCClass('NSException')
  NSFont = ObjCClass('NSFont')
  NSFontDescriptor = ObjCClass('NSFontDescriptor')
  NSFontManager = ObjCClass('NSFontManager')
  NSFontPanel = ObjCClass('NSFontPanel')
  NSImage = ObjCClass('NSImage')
  NSImageView = ObjCClass('NSImageView')
  NSLayoutManager = ObjCClass('NSLayoutManager')
  NSMenu = ObjCClass('NSMenu')
  NSMenuItem = ObjCClass('NSMenuItem')
  NSMutableArray = ObjCClass('NSMutableArray')
  NSMutableData = ObjCClass('NSMutableData')
  NSMutableDictionary = ObjCClass('NSMutableDictionary')
  NSMutableSet = ObjCClass('NSMutableSet')
  NSMutableString = ObjCClass('NSMutableString')
  NSNotification = ObjCClass('NSNotification')
  NSNotificationCenter = ObjCClass('NSNotificationCenter')
  NSNull = ObjCClass('NSNull')
  NSNumber = ObjCClass('NSNumber')
  NSObject = ObjCClass('NSObject')
  NSOpenPanel = ObjCClass('NSOpenPanel')
  NSPageLayout = ObjCClass('NSPageLayout')
  NSPrinter = ObjCClass('NSPrinter')
  NSPrintInfo = ObjCClass('NSPrintInfo')
  NSPrintOperation = ObjCClass('NSPrintOperation')
  NSPrintPanel = ObjCClass('NSPrintPanel')
  NSSavePanel = ObjCClass('NSSavePanel')
  NSScreen = ObjCClass('NSScreen')
  NSScrollView = ObjCClass('NSScrollView')
  NSSet = ObjCClass('NSSet')
  NSStatusBar = ObjCClass('NSStatusBar')
  NSString = ObjCClass('NSString')
  NSTableColumn = ObjCClass('NSTableColumn')
  NSTableView = ObjCClass('NSTableView')
  NSTextField = ObjCClass('NSTextField')
  NSTextView = ObjCClass('NSTextView')
  NSThread = ObjCClass('NSThread')
  NSURL = ObjCClass('NSURL')
  NSValue = ObjCClass('NSValue')
  NSView = ObjCClass('NSView')
  NSWindow = ObjCClass('NSWindow')
  NSBoolean = NSNumber.numberWithBool_
  NSDouble = NSNumber.numberWithDouble_
  NSFloat = NSNumber.numberWithDouble_
  NSInt = NSNumber.numberWithInt_
  NSLong = NSNumber.numberWithLong_
  NSLongLong = NSNumber.numberWithLongLong_
  NSMain = NSMain.Application=NSApplication(<Id_t at 0x7f9a7880f...
Global ObjC/NS/CF... singletons.
  NSMain.Application
Get the NSApplication.sharedApplication.
  NSMain.BooleanNO
Get NSBoolean(NO).
  NSMain.BooleanYES
Get NSBoolean(YES).
  NSMain.Bundle
Get the NSBundle.mainBundle.
  NSMain.BundleName
Get the NS/CFBundleName.
  NSMain.FontManager
Get the NSFontManager.sharedFontManager.
  NSMain.LayoutManager
Get the NSLayoutManager.
  NSMain.NO_false
Get NSfalse/NO.
  NSMain.Null
Get NSNull.
  NSMain.PrintInfo
Get the NSPrintInfo.
  NSMain.Screen
Get the NSScreen.mainScreen, once.
  NSMain.TableColumn
Get a blank NSTableColumn.
  NSMain.YES_true
Get NStrue/YES.
  NSMain.nil
Get NSnil.
  NSMain.stdlog
Get the standard log file (stdout, stderr, other).
  NSMain.versionstr
Get the PyCocoa, Python, macOS versions as str.
Function Details

isAlias(path)

 

Resolve a macOS file or folder alias.

Parameters:
  • path - The alias name (str or NSStr).
Returns:
The alias' target (str) or None if path isn't a macOS alias.

See Also: mac-alias and here.

isLink(path)

 

Resolve a file or folder link or alias.

Parameters:
  • path - The link or alias name (str or NSStr).
Returns:
The link's or alias' target (str) or None if path isn't a link or alias.

isNone(obj)

 

Return True if obj is None, NSMain.nil, NSMain.Null, etc.

Parameters:
Returns:
True or False (bool).

nsArray2listuple(ns, ctype=<class 'ctypes.c_void_p'>)

 

Create a Python list or tuple from an NS[Mutable]Array.

Parameters:
  • ns - The NS[Mutable]Array (ObjCInstance).
  • ctype - The array item type (ctypes).
Returns:
The array (list or tuple).

nsArray2tuple(ns, ctype=<class 'pycocoa.runtime.ObjCInstance'>)

 

Create a Python tuple from an immutable NSArray.

Parameters:
  • ns - The NSArray (ObjCInstance).
  • ctype - The array item type (ObjCInstance).
Returns:
The array (tuple).

nsBoolean2bool(ns, dflt=missing)

 

Create a Python bool from an NSBoolean.

Parameters:
  • ns - The NSBoolean (ObjCInstance).
  • dflt - Default for a missing, unobtainable value (missing).
Returns:
The bool (bool) of dlft.
Raises:
  • TypeError - Unexpected NumberType.

nsBundleRename(ns_title, match='Python')

 

Change the bundle title if the current title matches.

Parameters:
  • ns_title - New bundle title (NSStr).
  • match - Optional, previous title to match (str).
Returns:
The previous bundle title (str) or None.

Note: Used to mimick NSApplication.setTitle_(ns_title), the name of an App shown in the menu bar.

nsData2bytes(ns, dflt='')

 

Create Python bytes from NSData.

Parameters:
  • ns - The NSData (ObjCInstance).
  • dflt - Default for empty NSData (bytes).
Returns:
The bytes (bytes) or dflt.

nsDecimal2decimal(ns)

 

Create a Python Decimal from an NSDecimal.

Parameters:
Returns:
The decimal (Decimal).
Raises:
  • ValueError - If ns not an NSDecimal.

nsDictionary2dict(ns, ctype_keys=<class 'ctypes.c_void_p'>, ctype_vals=<class 'ctypes.c_void_p'>)

 

Create a Python dict from an NS[Mutable]Dictionary.

Parameters:
  • ns - The NSDictionary instance (ObjCInstance).
  • ctype_keys - The dictionary keys type (ctypes).
  • ctype_vals - The dictionary values type (ctypes).
Returns:
The dict (Adict).

nsDictionary2items(ns)

 

Yield the (key, value) items from an NSDictionary.

Parameters:
Returns:
A 2-tuple (key, value) for each item, each a separate ObjCInstance

nsException(name=None, reason='not given', **info)

 

Create an ObjC/NSException instance.

Parameters:
  • name - Ignored (NSExceptionName).
  • reason - The reason for the exception (str).
  • info - Other, caller-defined information (all keywords).

See Also: nsRaise, nsThrow and NSExceptionError.

Notes:
  • Use NSExceptionError(nsExc) to wrap a Python exception around an ObjC/NSException instance and get access to the attributes of the latter.
  • Raised and thrown NSExceptions can not be caught and result in fatal exiting.

nsIter(ns, reverse=False)

 

Iterate over an NS.. ObjC objects's (reverse) enumerator.

Parameters:
  • ns - The NS.. object to iterate over (ObjCInstance).
  • reverse - Iterate in reverse order (bool), forward otherwise.
Returns:
Each object (NS...).

nsIter2(ns, reverse=False)

 

Iterate over an NS.. ObjC objects's (reverse) enumerator.

Parameters:
  • ns - The NS.. object to iterate over (ObjCInstance).
  • reverse - Iterate in reverse order (bool), foward otherwise.
Returns:
Each object as 2-Tuple (py, ns) where py is a Python Type instance and ns the ObjC object NS....

nsLog(ns_fmt, *ns_args)

 

Formatted ObjC write to the console.

Parameters:
  • ns_fmt - A printf-like format string (NSStr).
  • ns_args - Optional arguments to format (all positional).

Note: The ns_fmt and all ns_args must be NS... ObjC instances.

See Also: Dglessus' nslog.py.

nsLogf(fmtxt, *args)

 

Formatted write to the console.

Parameters:
  • fmtxt - A printf-like format string (str).
  • args - Optional arguments to format (all positional).

See Also: nsLog.

nsNull2none(ns)

 

Return Python None for an NS/CFNull or nil.

Parameters:
Returns:
The singleton (None).
Raises:
  • ValueError - If ns not isNone.

nsNumber2num(ns, dflt=missing)

 

Create a Python Decimal, int or float from an NSNumber.

Parameters:
  • ns - The NSNumber (ObjCInstance).
  • dflt - Default for missing, unobtainable value (missing).
Returns:
The number (Decimal, int or float).
Raises:
  • TypeError - Unexpected NumberType.
  • ValueError - If ns not an NSNumber.

nsOf(inst)

 

Return the .NS ObjC object of a Python wrapper or Type instance.

Parameters:
Returns:
The .NS object (NS...).
Raises:
  • TypeError - No .NS for this inst.

nsRaise(name=None, reason='not given', **info)

 

Create an NSException and mimick @throw NSException.

Parameters:
  • name - Ignored (NSExceptionName).
  • reason - The reason for the exception (str).
  • info - Other, caller-defined information (all keywords).

Note: Raised NSExceptions can not be caught and result in fatal exiting.

See Also: NSException and nsThrow.

nsSet2set(ns, ctype=<class 'ctypes.c_void_p'>)

 

Create a Python set or frozenset from an NS[Mutable]Set.

Parameters:
  • ns - The NS[Mutable]Set (ObjCInstance).
  • ctype - The set item type (ctypes).
Returns:
The set (set or frozenset).

nsString2str(ns, dflt=None)

 

Create a Python str or unicode from an NS[Mutable]Str[ing].

Parameters:
Returns:
The string (str or unicode) or dflt.

nsTextSize3(text, ns_font=None)

 

Return the size of a multi-line text.

Parameters:
  • text - The text (str), including lineseparators.
  • ns_font - The text font (NSFont) or None.
Returns:
3-Tuple (width, height, lines) in (pixels, pixels) or in (characters, lines, lines) if ns_font is None.

nsThrow(nsExc)

 

Mimick ObjC's @throw NSException to raise an exception.

Parameters:
  • nsExc - The exception to raise (NSException).
Raises:
  • TypeError - Invalid nsExc.

See Also: NSException and nsRaise.

Note: Thrown NSExceptions can not be caught and result in fatal exiting.

nsURL2str(ns)

 

Create a Python str from NSURL string.

Parameters:
Returns:
The URL as string (str).

nsValue2py(ns, dflt=missing)

 

Create a Python instance from an NS[Concrete]Value.

Parameters:
  • ns - The NS[Concrete]Value (ObjCInstance).
  • dflt - Default for missing, unobtainable value.
Returns:
The value (NSPoint_t, NSRange_t, NSRect_t, NSSize_t or tuple) or dflt.
Raises:
  • TypeError - Invalid ns or unexpected ns.objCType.

ns2py(ns, dflt=missing)

 

Convert (an instance of) an ObjC class to an instance of the equivalent Python standard type or wrapper and value.

Parameters:
  • ns - The NS... (ObjCInstance).
  • dflt - Default for unhandled, unexpected NS...s (missing).
Returns:
The value (Python type) or dflt if provided.
Raises:
  • TypeError - Unhandled, unexpected TypeID.

Note: Conversion map:

  • NSArray -> tuple
  • NSBoolean -> bool
  • NSConstantString -> str
  • NSData -> bytes
  • NSDecimalNumber -> Decimal
  • NSDictionary -> dict
  • NSMutableArray -> list
  • NSMutableSet -> set
  • NSMutableString -> str
  • NSNumber -> int or float
  • NSNull -> None
  • NSSet -> frozenset
  • NSString -> str
  • NSStr -> str

See Also: Converting values between Python and Objective-C

ns2Type(ns)

 

Convert an NS... ObjC object to an instance of the corresponding Python Type and value.

Parameters:
Returns:
The value (Python Type).

ns2TypeID2(ns, dflt=None)

 

Get the NS... ObjC TypeID.

Parameters:
  • ns - The NS... (ObjCInstance).
  • dflt - Default for unhandled, unexpected NS...s (missing).
Returns:
2-Tuple (TypeID, ns...2py) of an intNS and the type conversion callable.

Variables Details

NSMain

Global ObjC/NS/CF... singletons.
Value:
NSMain.Application=NSApplication(<Id_t at 0x7f9a7880f680>) of 0x7f9a66\
350c20,
      .BooleanNO=NSBoolean(<Id_t at 0x7f9a482d40e0>) of 0x7ff8475e6c70\
,
      .BooleanYES=NSBoolean(<Id_t at 0x7f9a78824950>) of 0x7ff8475e6c6\
0,
      .Bundle=NSBundle(<Id_t at 0x7f9a78824a70>) of 0x600000ef4000,
      .BundleName=NSConstantString('CFBundleName'),
...