util—general utility functions

• cb—callback management
• grid—abstract grid representations

Abstract

dd(default, [items, ]**kwargs) → default_dict

Create a collections.defaultdict with a static default.

Parameters:

• default – the default value.
• items – dict or dict-like to initialise with.
• kwargs – extra items to initialise with.

Returns:

the created defaultdict.

ir(x)

Returns the argument rounded to the nearest integer.

This is about twice as fast as int(round(x)).

sum_pos(*pos)

Sum all given (x, y) positions component-wise.

pos_in_rect(pos, rect, round_val=False)

Return the position relative to rect given by pos.

Parameters:

• pos –

  a position identifier. This can be:

  • (x, y), where each is either a number relative to rect’s top-left, or the name of a property of pygame.Rect which returns a number.
  • a single number x that is the same as (x, x).
  • the name of a property of pygame.Rect which returns an (x, y) sequence of numbers.
• rect – a Pygame-style rect, or just a (width, height) size to assume a rect with top-left (0, 0).
• round_val – whether to round the resulting numbers to integers before returning.

Returns:

the qualified position relative to rect’s top-left, as (x, y) numbers.

normalise_colour(c)

Turn a colour into (R, G, B, A) format with each number from 0 to 255.

Accepts 3- or 4-item sequences (if 3, alpha is assumed to be 255), or an integer whose hexadecimal representation is 0xrrggbbaa, or a CSS-style colour in a string ('#rgb', '#rrggbb', '#rgba', '#rrggbbaa' - or without the leading '#').

call_in_nest(f, *args) → result

Collapse a number of similar data structures into one.

Used in interp_* functions.

Parameters:

• f – a function to call with elements of args.
• args – each argument is a data structure of nested lists with a similar format.

Returns:

a new structure in the same format as the given arguments with each non-list object the result of calling f with the corresponding objects from each arg.

For example:

>>> f = lambda n, c: str(n) + c
>>> arg1 = [1, 2, 3, [4, 5], []]
>>> arg2 = ['a', 'b', 'c', ['d', 'e'], []]
>>> call_in_nest(f, arg1, arg2)
['1a', '2b', '3c', ['4d', '5e'], []]

One argument may have a list where others do not. In this case, those that do not have the object in that place passed to f for each object in the (possibly further nested) list in the argument that does. For example:

>>> call_in_nest(f, [1, 2, [3, 4]], [1, 2, 3], 1)
[f(1, 1, 1), f(2, 2, 1), [f(3, 3, 1),  f(4, 3, 1)]]

However, in arguments with lists, all lists must be the same length.

bezier(t, *pts)

Compute a 1D Bézier curve point.

Parameters:

• t – curve parameter.
• pts – points defining the curve.

class Singleton(name)

Bases: object

For easily making singleton objects (eg. as identitfiers).

Parameters:name – string representation of the object.

name

String representation, as passed to the constructor.

class OwnError

Bases: exceptions.RuntimeError

Raised when taking ownership of an Owned instance fails.

class Owned([max_owners, ]on_full='throw')

Bases: object

Manage ‘owners’ of an object.

Parameters:

• max_owners – the maximum number of owners that this object can have (greater than zero).
• on_full –

  behaviour when taking ownership is attempted but the limited specified by max_owners has been reached. One of:

  • 'throw': raise an OwnError exception.
  • 'ignore': don’t add the owner.
  • 'replace': remove another owner (choice of owner to remove is undefined).

max_owners

As passed to the constructor.

owners

Set-like container of owner identifiers as passed to own.

owner

Identifier for any single owner of this instance, or None.

own(owner_id[, release_cb]) → success

Attempt to take ownership of this instance.

Parameters:

• owner_id – non-None hashable identifier for the owner, used for later removal.
• release_cb – optional function to call when this owner is removed (through release, or by being replaced by another owner if this instance allows it). This is called like release_cb(owned_instance, owner_id); if it is determined that the function cannot take any arguments, it is not given any.

Returns:

whether the attempt succeeded. If not, OwnError may be raised instead, depending on the on_full argument passed to the constructor.

release(owner_id)

Relinquish ownership of this instance.

Parameters:owner_id – identifier passed to own.

Random

randsgn()

Randomly return 1 or -1.

rand0()

Zero-centred random (-1 <= x < 1).

weighted_rand(ws) → index

Return a weighted random choice.

Parameters:ws – weightings, either a list of numbers to weight by or a {key: weighting} dict for any keys. Returns:the chosen index in the list or key in the dict.

Graphics

align_rect(rect, within, alignment = 0, pad = 0, offset = 0) → pos

Align a rect within another rect.

Parameters:

• rect – the Pygame-style rect to align.
• within – the rect to align rect within.
• alignment – (x, y) alignment; each is < 0 for left-/top-aligned, 0 for centred, > 0 for right-/bottom-aligned. Can be just one number to use on both axes.
• pad – (x, y) padding to leave around the inner edge of within. Can be negative to allow positioning outside of within, and can be just one number to use on both axes.
• offset – (x, y) amounts to offset by after all other positioning; can be just one number to use on both axes.

Returns:

the position the top-left corner of the rect should be moved to for the wanted alignment.

position_sfc(sfc, dest, alignment = 0, pad = 0, offset = 0, rect = sfc.get_rect(), within = dest.get_rect(), blit_flags = 0)

Blit a surface onto another with alignment.

alignment, pad, offset, rect and within are as taken by align_rect. Only the portion of sfc within rect is copied.

Parameters:

• sfc – source surface to copy.
• dest – destination surface to blit to.
• blit_flags – the special_flags argument taken by pygame.Surface.blit.

convert_sfc(sfc)

Convert a surface for blitting.

combine_drawn(*drawn)

Combine the given drawn flags.

These are as returned by engine.game.World.draw().

blank_sfc(size)

Create a transparent surface with the given (width, height) size.