pycocoa.utils

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

# Module utils

Utility functions, constants, internals, etc.

Version: 25.01.17

Classes
| module_property_RO Decorator for a `Read-Only` module property.
| Adict A `dict` with key and attribute access to the items and callable to add items.
| Cache2 Two-level cache implemented by two `dict`s, a primary level-1 `dict` and a secondary level-2 `dict`.

Functions
property_RO(method) Decorator for `Read_Only` class/instance property. |
bytes2repr(bytestr) Represent `bytes` or `str` as `b"..."`. |
bytes2str(bytestr, dflt=missing, name='') Convert `bytes`/`unicode` to `str` if needed. |
iterator |
iterbytes(collection) iter(callable, sentinel) -> iterator |
str2bytes(bytestr, dflt=missing, name='') Convert `str` to `bytes`/`unicode` if needed. |
aspect_ratio(width, *height, **Error_kwds) Compute the smallest, integer aspect ratio. |
clipstr(bytestr, limit=50) Clip a string to the given length limit. |
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, **name_missing) Check a Python instance' class. |
lambda1(arg) Inlieu of using lambda arg: arg. |
logf(fmt, *args, **kwds) Formatted log fmt % args with optional keywords. |
machine() Return the `platform.machine` string, distinguishing Intel from emulating Intel on Apple Silicon (on macOS). |
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(fmt, *args, **kwds) Formatted print fmt % args with optional keywords. |
properties(inst) All property names and values. |
property2(inst, name) Return the property `get` and `set` method. |
sortuples(iterable) Sort tuples alphabetically, case-insensitive. |
terminating(app, timeout=None) Set up a separate thread to terminate an NSApplication by calling the `.terminate_` method after the given timeout has elapsed. |
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`
| DEFAULT_UNICODE = ``'``utf-8``'``
| missing = `missing` Missing keyword argument value.

Function Details

### property_RO(method) |
Decorator for `Read_Only` class/instance property. Parameters: `method` - The callable to be decorated as `property`. Note: Like standard Python `property` without a `property.setter` with a more descriptive error message when set.

### bytes2repr(bytestr) |
Represent `bytes` or `str` as `b"..."`. Parameters: `bytestr` - `bytes` or `str`.. Returns: Representation `b'...'` (`str`).

### bytes2str(bytestr, dflt=missing, name='') |
Convert `bytes`/`unicode` to `str` if needed. Parameters: `bytestr` - `bytes`, `str` or `unicode`. `dflt` - Optional, default return value. `name` - Optional name of bytestr argument. Returns: `str` or dflt. Raises: `TypeError` - If neither `str` nor `bytes`, but only if no dflt is provided.

### iterbytes(collection) |
iter(callable, sentinel) -> iterator Get an iterator from an object. In the first form, the argument must supply its own iterator, or be a sequence. In the second form, the callable is called until it returns the sentinel. Returns: iterator

### str2bytes(bytestr, dflt=missing, name='') |
Convert `str` to `bytes`/`unicode` if needed. Parameters: `bytestr` - `bytes`, `str` or `unicode`. `dflt` - Optional, default return value. `name` - Optional name of bytestr argument. Returns: `bytes` or dflt. Raises: `TypeError` - If neither `bytes` nor `str`, but only if no dflt is provided.

### 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`). `strepr` - Conversion (`repr` or `str`). `attrs` - Instance attribute names (all positional). Returns: Instance representation (`str`).

### isinstanceOf(inst, *classes, **name_missing) |
Check a Python instance' class. Parameters: `inst` - The instance to check (any). `classes` - One or several classes (all positional). `name` - The name of the instance (`str`). Returns: The matching class from classes, None otherwise. Raises: `TypeError` - If inst does not match any of the classes, but iff keyword name='...' is provided. See Also: Function isObjCInstanceOf for checking ObjC instances.

### logf(fmt, *args, **kwds) |
Formatted log fmt % args with optional keywords. Parameters: `fmt` - Print-like format or plain string (`str`). `args` - Optional arguments to format (all positional). `argv0` - Optional prefix (`str`). `file` - Alternate file to write to (`file`-type), default `NSMain.stdlog`. `flush` - Flush `file` after writing (`bool`), default C(True). `nl` - Number of leading blank lines (`int`). `nt` - Number of trailing blank lines (`int`).

### 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 by `underscore`).

### 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(fmt, *args, **kwds) |
Formatted print fmt % args with optional keywords. Parameters: `fmt` - Print-like format or plain string (`str`). `args` - Optional arguments to format (all positional). `argv0` - Optional prefix (`str`). `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`).

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

### property2(inst, name) |
Return the property `get` and `set` method. Parameters: `inst` - An instance (`any`). `name` - Property name (`str`). Returns: 2-Tuple (get, set) as `callable`s, (`callable`, `None`) or (`None`, `None`) if inst.name is not a property.

### terminating(app, timeout=None) |
Set up a separate thread to terminate an NSApplication by calling the `.terminate_` method after the given timeout has elapsed. 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 terminates 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`). 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`).