pycocoa.utils

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

# Module utils

Private and public utility functions.

Version: 25.03.24

Functions
aspect_ratio(width, *height, **Error_kwds) Compute the smallest, integer aspect ratio. |
clipstr(bytestr, limit=50) Clip a string to the given length limit. |
errorf(fmtxt, *args, **file_flush_nl_nt_argv0) Like printf, but writing to file=sys.stderr. |
flint(f) Return `int` for integer `float`. |
gcd(a, b) Calculate the Greatest Common Divisor of a and b. |
inst2strepr(inst, strepr, *attrs) Convert an instance's attributes, maintaining the order. |
isinstanceOf(inst, *classes, **raiser_name) Check a Python instance' class. |
islistuple(inst) Is `inst`ance a `list` or `tuple`? |
logf(fmtxt, *args, **file_flush_nl_nt_argv0) Like printf, but writing to file=NSMain.stdlog. |
machine() Return the `platform.machine` string, distinguishing Intel from emulating Intel on Apple Silicon (on macOS). |
macOSver() Return the macOS release as `str`. |
macOSver2(n=2) Return the macOS release as 1-, 2- or 3-tuple of `int`s. |
name2objc(name_) Convert a (selector) name to `bytes` and ObjC naming rules. |
name2py(name_) Convert a (selector) name `str` and Python naming conventions. |
name2pymethod(name_) Convert a (selector) name to a valid Python callback method. |
printf(fmtxt, *args, **file_flush_nl_nt_argv0) Formatted print fmt % args with optional keywords. |
properties(inst) All property names and values. |
terminating(app, timeout=None) Set up a separate thread to terminate an NSApplication app by calling its `.terminate_` method at the given timeout in seconds. |
type2strepr(inst, strepr=<type 'str'>, **kwds) Represent a Python Type instance as `str` or `repr`. |
z1000str(size, sep='_') Convert a size to string with 1_000's seperator. |
zfstr(flt, prec=3) Format a `float` and strip trailing zero decimals. |
zSIstr(size, B=`'``B``'`, K=1024) Convert a size to string with SI-units suffix. |

Variables
| __all__ = `_ALL_LAZY.utils`

Function Details

### aspect_ratio(width, *height, **Error_kwds) |
Compute the smallest, integer aspect ratio. Parameters: `width` - The width (`float`, `int`, Size, 2-tuple (width, height), str("w:h") or `NSSize_t`). `height` - The height (`float` or `int`). Returns: 2-Tuple (width, height) as (`int`, `int`) or `None`. Example:
    >>> aspect_ratio(10, 15)
    (2, 3)
    >>> aspect_ratio(10.0, 15)
    (2, 3)
    >>> aspect_ratio(10, -15)
    (-2, 3)
    >>> aspect_ratio(-10, -15)
    (2, 3)
    >>> aspect_ratio(10.5, 15)
    (7, 10)
    >>> aspect_ratio(0, 15)
    ()

### clipstr(bytestr, limit=50) |
Clip a string to the given length limit. Parameters: `bytestr` - String (`bytes` or `str`). `limit` - Length limit (`int`). Returns: Clipped `bytes` or `str`.

### gcd(a, b) |
Calculate the Greatest Common Divisor of a and b. Unless b==0, the result will have the same sign as b (so that when b is divided by it, the result comes out positive).

### inst2strepr(inst, strepr, *attrs) |
Convert an instance's attributes, maintaining the order. Parameters: `inst` - Instance (`any`, incl. `ctypes`). `strepr` - Conversion (`repr` or `str`). `attrs` - Instance attribute names (all positional). Returns: Instance representation (`str`).

### isinstanceOf(inst, *classes, **raiser_name) |
Check a Python instance' class. Parameters: `inst` - The instance to check (`any`). `classes` - One or several classes (all positional). `raiser_name` - Optional instance name (`str`) to raise `TypeError`. Returns: The `type{inst} if `isinstance(inst, classes`` else `None`. Raises: `TypeError` - If inst does not match any of the classes but only if keyword `raiser` is specified. See Also: Function isObjCInstanceOf for checking ObjC instances.

### islistuple(inst) |
Is `inst`ance a `list` or `tuple`? Parameters: `inst` - The object (any `type`). Returns: `True` if `inst` is a `list` or `tuple`, `False` otherwise.

### machine() |
Return the `platform.machine` string, distinguishing Intel from emulating Intel on Apple Silicon (on macOS). Returns: Machine `'arm64'` for Apple Silicon, `"arm64_x86_64"` for Intel emulated, `'x86_64'` for Intel, etc. (`str` with any `comma`s replaced by `underscore`).

### macOSver() |
Return the macOS release as `str`. Note: `macOS 11 Big Sur` is `'10.16'` before Python 3.9.6 and on Apple Si Intel-emulation, see function machine.

### macOSver2(n=2) |
Return the macOS release as 1-, 2- or 3-tuple of `int`s. Note: `macOS 11 Big Sur` is `(10, 16)` before Python 3.9.6 and on Apple Si Intel-emulation, see function machine.

### name2objc(name_) |
Convert a (selector) name to `bytes` and ObjC naming rules. Parameters: `name_` - Name to convert (`str` or `bytes`). Returns: Converted name (`bytes`). Note: A name_ starting with an underscore is returned as-is.

### name2py(name_) |
Convert a (selector) name `str` and Python naming conventions. Parameters: `name_` - Name to convert (`str` or `bytes`). Returns: Converted name (`str`). Note: A name_ starting with an underscore is returned as-is.

### name2pymethod(name_) |
Convert a (selector) name to a valid Python callback method. Parameters: `name_` - Name to convert (`str` or `bytes`). Returns: Converted name (`str`). Raises: `ValueError` - Invalid, non-alphanumeric name_.

### printf(fmtxt, *args, **file_flush_nl_nt_argv0) |
Formatted print fmt % args with optional keywords. Parameters: `fmtxt` - Print-like format or plain string (`str`). `args` - Optional arguments to format (all positional). `file` - Alternate file to write to (`file`-type), default `sys.stdout`. `flush` - Flush `file` after writing (`bool`), default `False`. `nl` - Number of leading blank lines (`int`). `nt` - Number of trailing blank lines (`int`, default 1). `argv0` - Optional prefix (`str`). Returns: Number of bytes written (`int`).

### properties(inst) |
All property names and values. Parameters: `inst` - An instance (`any`). Returns: The properties (`dict`).

### terminating(app, timeout=None) |
Set up a separate thread to terminate an NSApplication app by calling its `.terminate_` method at the given timeout in seconds. Returns: Timeout in seconds (`float`) or `None`. Note: Similarly, the NSWindow could be closed, provided the NSWindow or NSApplication `Delegate` instance includes the `.windowWillClose_` method which in turn invokes the NSApplication's `.terminate_` method.

### type2strepr(inst, strepr=<type 'str'>, **kwds) |
Represent a Python Type instance as `str` or `repr`. Parameters: `inst` - Instance (`any`). `strepr` - Representation function (`repr` or `str`). `kwds` - Optional, additional `name=value` arguments. Returns: Instance representation (`str`).

### z1000str(size, sep='_') |
Convert a size to string with 1_000's seperator. Parameters: `size` - Value to convert (`float` or `int`). `sep` - 1_000's separator (`str`). Returns: "<1or2digits><sep><3digits>..." or "-" if size is negative (`str`).

### zfstr(flt, prec=3) |
Format a `float` and strip trailing zero decimals. Parameters: `flt` - Value (`float`). `prec` - Number of decimals (`int`). Returns: Value (`str`).

### zSIstr(size, B=`'``B``'`, K=1024) |
Convert a size to string with SI-units suffix. Parameters: `size` - Value to convert (`float` or `int`). `B` - The unit (`str`). `K` - 1024 or 1000 (`int`). Returns: "<Size> <SI>[i]<B>" (`str`).