pycocoa.nstypes

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

# Module nstypes

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

Version: 25.03.18

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'>, typy=None) Create a Python `list` or `tuple` from an `NS[Mutable]Array`. |
nsArray2tuple(ns, ctype=<class 'pycocoa.runtime.ObjCInstance'>, typy=<type 'tuple'>) 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'>, typy=None) Create a Python `dict` or `frozendict` from an `NS[Mutable|Frozen]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, keys=False) Iterate over an `NS..` ObjC objects's keys, values or reverse values. |
nsIter2(ns, reverse=False, keys=False) Iterate over an `NS..` ObjC objects's keys or (reverse) values. |
nsLog(ns_fmt, *ns_args) Formatted ObjC write to the console. |
nsLogf(fmtxt, *args) Formatted write to the console. |
ns2NSType2(ns) Get the main `NS[Mutable]...` class and Python Type. |
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. |
ns2py(ns, dflt=missing) Convert an ObjC class' instance to the equivalent Python standard type's instance or wrapper and value. |
nsRaise(name=None, reason=`'``not given``'`, **info) Create an `NSException` and mimick `@throw NSException`. |
nsSet2set(ns, ctype=<class 'ctypes.c_void_p'>, typy=None) 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, scroll=50) Return an `NSTextView` for the given text string. |
nsThrow(nsExc) Mimick ObjC's `@throw NSException` to raise an exception. |
ns2Type(ns) Convert an `NS...` ObjC object to an instance of the corresponding Python Type, capital T!. |
ns2TypeID2(ns, dflt=None) Get the `NS...` ObjC `TypeID`. |
nsURL2str(ns) Create a Python `str` from `NSURL` string. |
nsValue2py(ns, dflt=missing) Create a Python instance from an `NS[Concrete]Value`. |

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 0x7f8118e90`...`` 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. Raises: `TypeError` - Invalid path. 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. Raises: `TypeError` - Invalid path.

### isNone(obj) |
Return True if obj is `None, NSMain.nil, NSMain.Null`, etc. Parameters: `obj` - The object (ObjCInstance). Returns: True or False (`bool`).

### nsArray2listuple(ns, ctype=<class 'ctypes.c_void_p'>, typy=None) |
Create a Python `list` or `tuple` from an `NS[Mutable]Array`. Parameters: `ns` - The `NS[Mutable]Array` instance (ObjCInstance). `ctype` - The array item type (`ctypes`). `typy` - Use `typy=list`, `typy=tuple` or `typy=any_callable` to override the Python type. Returns: The array (`list` or `tuple` or `typy`). Raises: `TypeError` - Invalid ns.

### nsArray2tuple(ns, ctype=<class 'pycocoa.runtime.ObjCInstance'>, typy=<type 'tuple'>) |
Create a Python `tuple` from an immutable `NSArray`. Parameters: `ns` - The `NSArray` instance (ObjCInstance). `ctype` - The array item type (`ObjCInstance`). `typy` - Use `typy=any_callable` to override the Python `tuple` type. Returns: The array (`tuple` or `typy`). Raises: `TypeError` - Invalid ns.

### nsBoolean2bool(ns, dflt=missing) |
Create a Python `bool` from an `NSBoolean`. Parameters: `ns` - The `NSBoolean` instance (ObjCInstance). `dflt` - Default for a missing, unobtainable value (`missing`). Returns: The bool (`bool`) of dlft. Raises: `TypeError` - Invalid ns.

### 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. Raises: `TypeError` - Invalid ns. 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` instance (ObjCInstance). `dflt` - Default for empty `NSData` (`bytes`). Returns: The bytes (`bytes`) or dflt. Raises: `TypeError` - Invalid ns.

### nsDecimal2decimal(ns) |
Create a Python `Decimal` from an `NSDecimal`. Parameters: `ns` - The `NSDecimal` instance (ObjCInstance). Returns: The decimal (`Decimal`). Raises: `TypeError` - If ns not `NSDecimal`.

### nsDescription2dict(ns, **defaults) |
Create an immutable `dict` object with key and attribute access to items by name. Parameters: `ns` - The `NS...` instance (ObjCInstance). `defaults` - Optional defaults items (Any kwds).

### nsDictionary2dict(ns, ctype_keys=<class 'ctypes.c_void_p'>, ctype_vals=<class 'ctypes.c_void_p'>, typy=None) |
Create a Python `dict` or `frozendict` from an `NS[Mutable|Frozen]Dictionary`. Parameters: `ns` - The `NSDictionary` instance (ObjCInstance). `ctype_keys` - The dictionary keys type (`ctypes`). `ctype_vals` - The dictionary values type (`ctypes`). `typy` - Use `typy=dict`, `typy=Adict`, `typy=frozendict` or `typy=any_callable` to override the Python type. Returns: The dict (Adict or `frozendict` or `typy`). Raises: `TypeError` - Invalid ns.

### nsDictionary2items(ns) |
Yield the `(key, value)` items from an `NSDictionary`. Parameters: `ns` - The `NSDictionary` instance (ObjCInstance). Returns: A 2-tuple `(key, value)` for each item, where each `key` and `value` is an ObjCInstance. Raises: `TypeError` - Invalid ns.

### 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`). Returns: The exception (`ObjC/NSException`). 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 `NSException`s can not be caught and result in fatal exiting.

### nsIter(ns, reverse=False, keys=False) |
Iterate over an `NS..` ObjC objects's keys, values or reverse values. Parameters: `ns` - The `NS..` instance to iterate over (ObjCInstance). `reverse` - If `True`, iterate in reverse otherwise forward order over `ns`' values (`bool`). `keys` - If `True`, iterate over `ns`' keys, provided `ns` is an `NS[Mutable]Dictionary` and ignoring `reverse`. Returns: Yield each object or key (`NS...`). Raises: `TypeError` - Invalid ns. Note: If `ns` is an `NS[Mutable]Dictionary` and `keys=False`, the values of `ns` are enumerated in forward or `reverse` order.

### nsIter2(ns, reverse=False, keys=False) |
Iterate over an `NS..` ObjC objects's keys or (reverse) values. Returns: Yield each object as 2-Tuple (py, ns) where py is a Python `Type` instance and ns the object `NS...`. Raises: `TypeError` - Invalid ns. See Also: Function nsIter for `ns`, `reverse` and `key` details and function ns2Type for Python `Type`s.

### 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`). Raises: `TypeError` - Invalid ns_fmt. 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`). Raises: `TypeError` - Invalid fmtxt. See Also: nsLog.

### ns2NSType2(ns) |
Get the main `NS[Mutable]...` class and Python Type. Parameters: `ns` - The `NS...` instance (ObjCInstance). Returns: 2-Tuple `(NS, Type)` with the `NS[Mutable]...` class and Python Type, either may be `None`. Raises: `TypeError` - Invalid ns. See Also: Functions ns2Type and ns2TypeID2.

### nsNull2none(ns) |
Return Python `None` for an `NS/CFNull` or `nil`. Parameters: `ns` - The `NS...` instance (ObjCInstance). Returns: The singleton (`None`). Raises: `TypeError` - Invalid ns. `ValueError` - If ns not `isNone`.

### nsNumber2num(ns, dflt=missing) |
Create a Python `Decimal`, `int` or `float` from an `NSNumber`. Parameters: `ns` - The `NSNumber` instance (ObjCInstance). `dflt` - Default for missing, unobtainable value (`missing`). Returns: The number (`Decimal`, `int` or `float`). Raises: `TypeError` - Invalid ns. `ValueError` - If ns not an `NSNumber`.

### nsOf(inst) |
Return the `.NS` ObjC object of a Python wrapper or Type instance. Parameters: `inst` - The wrapper (ObjCInstance or `Python Type`). Returns: The `.NS` object (`NS...`). Raises: `TypeError` - No `.NS` for this inst.

### ns2py(ns, dflt=missing) |
Convert an ObjC class' instance to the equivalent Python standard type's instance or wrapper and value. Parameters: `ns` - The `NS...` instance (ObjCInstance). `dflt` - Default for unhandled, unexpected `NS...`s (`missing`). Returns: The value (`Python type`) or dflt if provided. Raises: `TypeError` - Invalid ns or unhandled `TypeID`. Note: Conversion map: NSArray -> tuple NSBoolean -> bool NSConstantString -> str NSData -> bytes NSDecimalNumber -> Decimal NSDictionary -> frozendict NSMutableArray -> list NSMutableDictionary -> dict NSMutableSet -> set NSMutableString -> str NSNumber -> int or float NSNull -> None NSSet -> frozenset NSStr -> str NSString -> str See Also: Converting values between Python and Objective-C

### 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 `NSException`s can not be caught and result in fatal exiting. See Also: NSException and nsThrow.

### nsSet2set(ns, ctype=<class 'ctypes.c_void_p'>, typy=None) |
Create a Python `set` or `frozenset` from an `NS[Mutable]Set`. Parameters: `ns` - The `NS[Mutable]Set` instance (ObjCInstance). `ctype` - The set item type (`ctypes`). `typy` - Use `typy=set`, `typy=frozenset` or `typy=any_callable` to override the Python type. Returns: The set (`set` or `frozenset` or `typy`). Raises: `TypeError` - Invalid ns.

### nsString2str(ns, dflt=None) |
Create a Python `str` or `unicode` from an `NS[Mutable]Str[ing]`. Parameters: `ns` - The `NS[Mutable]Str[ing]` instance (ObjCInstance). 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 `linesep`arators. `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`.

### nsTextView(text, ns_font, scroll=50) |
Return an `NSTextView` for the given text string. Parameters: `scroll` - Make the `NSTextView` scrollable if the number of text lines exceeds `scroll` (`int`).

### 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 `NSException`s can not be caught and result in fatal exiting.

### ns2Type(ns) |
Convert an `NS...` ObjC object to an instance of the corresponding Python Type, capital T!. Parameters: `ns` - The `NS...` instance (ObjCInstance). Returns: The instance (`Python Type`).

### ns2TypeID2(ns, dflt=None) |
Get the `NS...` ObjC `TypeID`. Parameters: `ns` - The `NS...` instance (ObjCInstance). `dflt` - Default for unhandled, unexpected `NS...`s (`missing`). Returns: 2-Tuple `(TypeID, ns...2py)` of an `int`NS and the type conversion `callable`. Raises: `TypeError` - Invalid ns.

### nsURL2str(ns) |
Create a Python `str` from `NSURL` string. Parameters: `ns` - The `CFURL` instance (ObjCInstance). Returns: The URL as string (`str`). Raises: `TypeError` - Invalid ns.

### nsValue2py(ns, dflt=missing) |
Create a Python instance from an `NS[Concrete]Value`. Parameters: `ns` - The `NS[Concrete]Value` instance (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 unhandled `ns.objCType`. `TypeError` - Invalid ns.

Variables Details

  ### NSMain Global `ObjC/NS/CF...` singletons. Value:
      NSMain.Application=NSApplication(<Id_t at 0x7f8118e90b90>) of 0x7f8133
      ff7890,
            .BooleanNO=NSBoolean(<Id_t at 0x7f8118e90830>) of 0x7ff85bd2f088
      ,
            .BooleanYES=NSBoolean(<Id_t at 0x7f8118e937a0>) of 0x7ff85bd2f07
      8,
            .Bundle=NSBundle(<Id_t at 0x7f8118e904d0>) of 0x600000d705a0,
            .BundleName=NSConstantString('CFBundleName'),
      ...