Misc Utility Functions

arcade.configure_logging(level: int | None = None)[source]

Set up basic logging.

Parameters:

level – The log level. Defaults to DEBUG.

class arcade.utils.Chain(*components: Sequence[_T])[source]

Bases: Generic[_T]

A reusable OOP version of itertools.chain.

In some cases (physics engines), we need to iterate over multiple sequences of objects repeatedly. This class provides a way to do so which:

  • Is non-exhausting

  • Avoids copying all items into one joined list

Parameters:

components – The sequences of items to join.

arcade.utils.as_type(item: Any) type[source]

If item is not a type, return its type. Otherwise, return item as-is.

Parameters:

item – A type or instance of one.

arcade.utils.type_name(item: Any) str[source]

Get the name of item if it’s a type or the name of its type if it’s an instance.

This is meant to help shorten debugging-related code and developer utilities. It isn’t meant to be a performant tool.

Parameters:

item – A type or an instance of one.

arcade.utils.is_iterable(item: Any) bool[source]

Use iter() to infer whether item is iterable.

Tip

An empty iterable still counts as an iterable.

This relies on the following:

  1. Python’s iter() raises a TypeError if item is not iterable

  2. try/catch blocks are fast

If you are still concerned about performance, you may want to inline the contents of this function locally since function calls may have more overhead than try/catch blocks on your Python version.

Parameters:

item – An object to pass to the built-in iter() function.

Returns:

True if the item appears to be iterable.

arcade.utils.is_nonstr_iterable(item: Any) bool[source]

True if item is an iterable other than a str.

In addition to calling this function if and elif statements, you can also pass it as an argument to other functions. These include:

Note

This is the opposite of is_str_or_noniterable().

Parameters:

item – Any object.

Returns:

Whether item is a non-string iterable.

arcade.utils.is_str_or_noniterable(item: Any) bool[source]

True if item is a string or non-iterable.

In addition to calling this function in if and elif statements, you can also pass it as an argument to other functions. These include:

Note

This is the opposite of is_str_or_noniterable().

Parameters:

item – Any object.

Returns:

True if item is a str or a non-iterable object.

arcade.utils.grow_sequence(destination: ~collections.abc.MutableSequence[~arcade.utils._T], source: ~arcade.utils._T | ~typing.Iterable[~arcade.utils._T], append_if: ~typing.Callable[[~arcade.utils._T | ~typing.Iterable[~arcade.utils._T]], bool] = <function is_str_or_noniterable>) None[source]

Append when append_if(to_add) is True, extend otherwise.

If performance is critical, consider inlining this code. This function is meant as:

  • a companion to arcade.types.OneOrIterableOf

  • an abbreviation for repetitive if-blocks in config and settings menus

The default append_if value is the is_str_or_noniterable() function in this module. You can pass any Callable() which returns:

  • True if we should append

  • False if we should extend

This includes both the callable function and your own custom functions. For example:

dest = []

def _validate_and_choose(item) -> bool:
    """Raises an exception if data is invalid or a bool if not."""
    ...

# Okay values
grow_sequence(dest, MyType(), append_when=_validate_and_choose)
grow_sequence(dest, [MyType(), MyType()], append_when=_validate_and_choose)

# Raises an exception
grow_sequence(dest, BadType(), append_when=_validate_and_choose)
Parameters:
  • destination – A list() or other MutableSequence to append to or extend.

  • source – A value source we’ll use to grow the destination sequence.

  • append_if – A callable() which returns True when source should be appended.

arcade.utils.copy_dunders_unimplemented(decorated_type: _TType) _TType[source]

Decorator stubs dunders raising NotImplementedError.

Temp fixes https://github.com/pythonarcade/arcade/issues/2074 by stubbing the following instance methods:

Example usage:

import copy
from arcade,utils import copy_dunders_unimplemented
from arcade.hypothetical_module import HypotheticalNasty

# Example usage
@copy_dunders_unimplemented
class CantCopy:
     def __init__(self, nasty_state: HypotheticalNasty):
         self.nasty_state = nasty_state

instance = CantCopy(HypotheticalNasty())

# These raise NotImplementedError
this_line_raises = copy.deepcopy(instance)
this_line_also_raises = copy.copy(instance)
arcade.utils.is_raspberry_pi() bool[source]

Determine if the host is a raspberry pi.

arcade.utils.get_raspberry_pi_info() tuple[bool, str, str][source]

Determine if the host is a raspberry pi with additional info.

Returned tuple format is:

bool (is host a raspi)
str (architecture)
str (model name)
arcade.utils.unpack_asfloat_or_point(value: float | int | tuple[float | int, float | int] | Vec2) tuple[float | int, float | int] | Vec2[source]

A utility method that converts a float or int into a Point2, or validates that an iterable is a Point2.

Note

This should be inlined in hot code paths

Parameters:

value – The value to test.

Returns:

A Point2 that is either equal to value, or is equal to (value, value)