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 dicts, 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 commas 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 callables, (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).