pyecs.helpers

pyecs.helpers#

class pyecs.helpers.StatusCodes(*values)[source]#
ENTITY_CREATED = 100#
ENTITY_DESTROYED = 101#
ENTITY_ACTIVE = 102#
ENTITY_INACTIVE = 103#
COMPONENT_ADDED = 200#
COMPONENT_REMOVED = 201#
COMPONENT_UPDATED = 202#
COMPONENT_NOT_FOUND = 203#
SYSTEM_REGISTERED = 300#
SYSTEM_UNREGISTERED = 301#
SYSTEM_STARTED = 302#
SYSTEM_STOPPED = 303#
SYSTEM_ERROR = 304#
QUERY_SUCCESS = 400#
QUERY_NO_RESULTS = 401#
QUERY_INVALID = 402#
SUCCESS = 0#
FAILURE = -1#
PENDING = 1#
NOT_INITIALIZED = 2#
pyecs.helpers.auto_unsafe(cls)[source]#

Class decorator that automatically generates unsafe versions for all methods that return StatusCodes.FAILURE.

Return type:

type[TypeVar(C)]

Parameters:

cls (type[C])

Usage:

@auto_unsafe class ECSWorld:

def get_component(self, …) -> Component | Literal[StatusCodes.FAILURE]:

…

pyecs.helpers.deprecated_ecs(reason=None, use_instead=None)[source]#

ECS-specific deprecation decorator that includes version information.

Parameters:

  • reason (str | None) – Optional reason for deprecation

  • use_instead (str | None) – Optional alternative function/method to use

Return type:

Callable[[Callable[[ParamSpec(P)], TypeVar(R)]], Callable[[ParamSpec(P)], TypeVar(R)]]

pyecs.helpers.deprecated_external(reason=None, use_instead=None, allowed_modules=None)[source]#

Deprecation decorator that only warns for external calls.

Parameters:

  • reason (str | None) – Optional reason for deprecation

  • use_instead (str | None) – Optional alternative to suggest

  • allowed_modules (list[str] | None) – List of module names that are allowed to call without warning

Return type:

Callable[[Callable[[ParamSpec(P)], TypeVar(R)]], Callable[[ParamSpec(P)], TypeVar(R)]]

pyecs.helpers.generate_unsafe(exception_type=<class 'pyecs.exceptions.Exceptions.OperationFailedError'>, error_message=None)[source]#

Decorator that automatically generates an unsafe version of a method.

The unsafe version raises an exception instead of returning StatusCodes.FAILURE. The decorated function gets a new unsafe attribute that is the exception-raising version.

Return type:

Callable[[Callable[[ParamSpec(P)], TypeVar(R)]], Callable[[ParamSpec(P)], TypeVar(R)]]

Parameters:
Usage:

@generate_unsafe(ComponentNotFoundError, “Component not found on entity”) def get_component(self, entity: Entity, component_type: type[Component]) -> Component | Literal[StatusCodes.FAILURE]:

…

# This automatically generates: # Safe version: component = world.get_component(entity, Position) # Returns FAILURE on error # Strict version: component = world.get_component_or_raise(entity, Position) # Raises exception on error

pyecs.helpers.process_unsafe_methods(cls)[source]#

Process all methods decorated with @generate_unsafe and add their unsafe versions to the class.

Return type:

type[TypeVar(C)]

Parameters:

cls (type[C])

pyecs.helpers.warn_deprecated(message, use_instead=None, stacklevel=3)[source]#

Issue a deprecation warning for usage patterns that can’t be decorated.

Parameters:

  • message (str) – The deprecation message

  • use_instead (str | None) – Optional alternative to suggest

  • stacklevel (int) – Stack level for warning (default 3)

Return type:

None

Modules

Deprecation

Statuses

Unsafe

Contents