esper 3.2__tar.gz → 3.4__tar.gz

esper-3.4/.ruff.toml

@@ -0,0 +1,2 @@
+lint.select = ["F", "E", "W", "C90", "B", "A", "C4", "G", "T20", "PT", "SLF", "TCH", "RET", "N", "ARG"]
+lint.ignore = ["E501"]

{esper-3.2 → esper-3.4}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2023 Benjamin Moran
+Copyright (c) 2024 Benjamin Moran
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{esper-3.2 → esper-3.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: esper
-Version: 3.2
+Version: 3.4
 Summary: esper is a lightweight Entity System (ECS) for Python, with a focus on performance
 Author-email: Benjamin Moran <benmoran@protonmail.com>
 Requires-Python: >=3.8
@@ -12,12 +12,12 @@ Project-URL: Home, https://github.com/benmoran56/esper
 [![rtd](https://readthedocs.org/projects/esper/badge/?version=latest)](https://esper.readthedocs.io)
 [![PyTest](https://github.com/benmoran56/esper/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/benmoran56/esper/actions/workflows/unit-tests.yml)
 
-Esper is a lightweight Entity System module for Python, with a focus on performance
+esper is a lightweight Entity System module for Python, with a focus on performance
 ===================================================================================
 
-Esper is an MIT licensed Entity System, or, Entity Component System (ECS).
+**esper** is an MIT licensed Entity System, or, Entity Component System (ECS).
 The design is based on the Entity System concepts originally popularized by
-Adam Martin and others. The primary focus for esper is to maximize perfomance,
+Adam Martin and others. The primary focus for **esper** is to maximize perfomance,
 while handling most common use cases. 
 
 For more information on the ECS pattern, you might find the following
@@ -30,7 +30,7 @@ API documentation is hosted at ReadTheDocs: https://esper.readthedocs.io
 Due to the small size of the project, this README currently serves as general usage
 documentation.
 
-> :warning: **Esper 3.0 introduces breaking changes**. Version 3.0 removes the
+> :warning: **esper 3.0 introduces breaking changes**. Version 3.0 removes the
 > World object, and migrates its methods to module level functions. Multiple 
 > contexts can be created and switched between. The v2.x README can be found
 > here: https://github.com/benmoran56/esper/blob/v2_maintenance/README.md
@@ -51,15 +51,15 @@ documentation.
 
 Compatibility
 =============
-Esper attempts to target all currently supported Python releases (any Python version that is
-not EOL). Esper is written in 100% pure Python, so *any* compliant interpreter should work.
+**esper** attempts to target all currently supported Python releases (any Python version that is
+not EOL). **esper** is written in 100% pure Python, so *any* compliant interpreter should work.
 Automated testing is currently done for both CPython and PyPy3.
 
 
 Installation
 ============
-Esper is a pure Python package with no dependencies, so installation is flexible.
-You can simply copy the *esper* folder right into your project, and *import esper*.
+**esper** is a pure Python package with no dependencies, so installation is flexible.
+You can simply copy the `esper` folder right into your project, and `import esper`.
 You can also install into your site-packages from PyPi via `pip`::
 
     pip install --user --upgrade esper
@@ -74,8 +74,8 @@ Design
 
 * World Context
 
-Esper uses the concept of "World" contexts. When you first `import esper`, a default context is
-active. You create Entities, assign Components, register Processesors, etc., by calling functions
+**esper** uses the concept of "World" contexts. When you first `import esper`, a default context is
+active. You create Entities, assign Components, register Processors, etc., by calling functions
 on the `esper` module. Entities, Components and Processors can be created, assigned, or deleted
 while your game is running. A simple call to `esper.process()` is all that's needed for each
 iteration of your game loop. Advanced users can switch contexts, which can be useful for
@@ -84,18 +84,19 @@ isolating different game scenes that have different Processor requirements.
 
 * Entities 
 
-Entities are simple integer IDs (1, 2, 3, 4, etc.).
-Entities are "created", but they are generally not used directly. Instead, they are
-simply used as IDs in the internal Component database to track collections of Components.
-Creating an Entity is done with the `esper.create_entity()` function.
-
+Entities are defined internally as plain integer IDs (1, 2, 3, 4, etc.). Generally speaking
+you should not need to care about the individual entity IDs, since entities are queried based
+on their specific combination of Components - not by their ID. An Entity can be thought of as
+a specific combination of Components. Creating an Entity is done with the `esper.create_entity()`
+function. You can pass Component instances on creation or add/remove them later.
 
 * Components
 
-Components are defined as simple Python classes. In keeping with a pure Entity System
-design philosophy, they should not contain any logic. They might have initialization
-code or perhaps Python properties, but no processing logic whatsoever. A simple
-Component can be defined as::
+Components are defined as simple Python classes. In keeping with a pure Entity System design
+philosophy, Components should not contain any processing logic. They may contain initialization
+logic, and you can take advantage of Python language features, like properties, to simplify data
+lookup. The key point is that game logic does not belong in these classes, and Components should
+have no knowledge of other Components or Entities. A simple Component can be defined as::
 
     class Position:
         def __init__(self, x=0.0, y=0.0):
@@ -114,11 +115,26 @@ be repeated, and you can still instantiate the Component with positional or keyw
         x: float = 0.0
         y: float = 0.0
 
+Python language features, like properties, can be useful to simplify data access. For example,
+a Body component that is often repositioned may benefit from a local AABB (axis aligned bounding
+box) property::
+
+    @dataclass
+    class Body:
+        width:  int
+        height: int
+        pos_x:  float = 0
+        pos_y:  float = 0
+
+        @property
+        def aabb(self) -> tuple[float, float, float, float]:
+            return self.pos_x, self.pos_y, self.pos_x + self.width, self.pos_y + self.height
+
 
 * Processors
 
 Processors, also commonly known as "Systems", are where all processing logic is defined and executed.
-All Processors must inherit from the *esper.Processor* class, and have a method called *process*.
+All Processors must inherit from the `esper.Processor` class, and have a method called `process`.
 Other than that, there are no restrictions. You can define any additional methods you might need. 
 A simple Processor might look like::
 
@@ -129,21 +145,31 @@ A simple Processor might look like::
                 pos.x += vel.x
                 pos.y += vel.y
 
-In the above code, you can see the standard usage of the *esper.get_components()* function. This
+In the above code, you can see the standard usage of the `esper.get_components()` function. This
 function allows efficient iteration over all Entities that contain the specified Component types.
 This function can be used for querying two or more components at once. Note that tuple unpacking
-is necessary for the return component pairs: *(vel, pos)*.  In addition the Components, you also
-get a reference to the Entity ID (the *ent* object) for the current pair of Velocity/Position
-Components. This entity ID can be useful in a variety of cases. For example, if your Processor
-will need to delete certain Entites, you can call the *esper.delete_entity()* function on
-this Entity ID. Another common use is if you wish to add or remove a Component on this Entity
-as a result of some condition being met. 
+is necessary for the return component pairs: `(vel, pos)`.  In addition to Components, you also
+get a reference to the Entity ID for the current pair of Velocity/Position Components. This entity
+ID can be useful in a variety of cases. For example, if your Processor will need to delete certain
+Entites, you can call the `esper.delete_entity()` function on this Entity ID. Another common use
+is if you wish to add or remove a Component on this Entity as a result of some condition being met. 
+For example, an Entity that should be deleted once it's `Lifecycle` Component reaches 0::
+
+    class LifecycleProcessor(esper.Processor):
+        def __init__(self, ...):
+            ...
+    
+        def process(self, dt):
+            for ent, (life, rend) in esper.get_components(Lifecycle, Renderable):
+                life.lifespan -= dt
+                if life.lifespan <= 0:
+                    esper.delete_entity(ent)
 
 
 Quick Start
 ===========
 
-To get started, simply import esper::
+To get started, simply import **esper**::
 
     import esper
 
@@ -159,7 +185,7 @@ Optionally, Component instances can be assigned directly to the Entity on creati
 
 
 Design some Processors that operate on these Component types, and then register them with
-Esper for processing. You can specify an optional priority (higher numbers are processed first).
+**esper** for processing. You can specify an optional priority (higher numbers are processed first).
 All Processors are priority "0" by default::
 
     movement_processor = MovementProcessor()
@@ -172,18 +198,17 @@ All Processors are priority "0" by default::
     esper.add_processor(SomeProcessor())
 
 
-Executing all Processors is done with a single call to esper.process(). This will call the
+Executing all Processors is done with a single call to `esper.process()`. This will call the
 `process` method on all assigned Processors, in order of their priority. This is usually called
 once per frame update of your game (every tick of the clock).::
 
     esper.process()
 
 
-**Note:** You can pass any arguments (or keyword arguments) you need to *esper.process()*, but you
-must also make sure to receive them properly in the *process()* methods of your Processors. For
-example, if you pass a delta time argument as *esper.process(dt)*, your Processor's *process()*
-methods should all receive it as:
-*def process(self, dt):*
+**Note:** You can pass any arguments (or keyword arguments) you need to `esper.process()`, but you
+must also make sure to receive them properly in the `process()` methods of your Processors. For
+example, if you pass a delta time argument as `esper.process(dt)`, your Processor's `process()`
+methods should all receive it as: `def process(self, dt):`
 This is appropriate for libraries such as **pyglet**, which automatically pass a delta time value
 into scheduled functions.  
 
@@ -193,14 +218,13 @@ General Usage
 
 World Contexts
 --------------
-Esper has the capability of supporting multiple "World" contexts. On import, a "default" World is
+**esper** has the capability of supporting multiple "World" contexts. On import, a "default" World is
 active. All creation of Entities, assignment of Processors, and all other operations occur within
 the confines of the active World. In other words, the World contexts are completely isolated from
 each other. For basic games and designs, you may not need to bother with this functionality. A
 single default World context can often be enough. For advanced use cases, such as when different
 scenes in your game have different Entities and Processor requirements, this functionality can be
 quite useful. World context operations are done with the following functions::
-* 
 * esper.list_worlds()
 * esper.switch_world(name)
 * esper.delete_world(name)
@@ -212,7 +236,7 @@ delete the currently active World.
 Adding and Removing Processors
 ------------------------------
 You have already seen examples of adding Processors in an earlier section. There is also a
-*remove_processor* function available:
+`remove_processor` function available:
 
 * esper.add_processor(processor_instance)
 * esper.remove_processor(ProcessorClass)
@@ -228,10 +252,10 @@ remove Components inside your Processors. The following functions are available
 * esper.add_component(entity_id, component_instance)
 * esper.remove_component(entity_id, ComponentClass)
 
-As an example of this, you could have a "Blink" component with a *duration* attribute. This can be used
+As an example of this, you could have a "Blink" component with a `duration` attribute. This can be used
 to make certain things blink for s specific period of time, then disappear. For example, the code below
 shows a simplified case of adding this Component to an Entity when it takes damage in one processor. A 
-dedicated *BlinkProcessor* handles the effect, and then removes the Component after the duration expires::
+dedicated `BlinkProcessor` handles the effect, and then removes the Component after the duration expires::
 
     class BlinkComponent:
         def __init__(self, duration):
@@ -274,16 +298,16 @@ to it, the following functions are available:
 * esper.component_for_entity
 * esper.components_for_entity
 
-The *component_for_entity* function is useful in a limited number of cases where you know a specific
+The `component_for_entity` function is useful in a limited number of cases where you know a specific
 Entity ID, and wish to get a specific Component for it. An error is raised if the Component does not
-exist for the Entity ID, so it may be more useful when combined with the *has_component*
+exist for the Entity ID, so it may be more useful when combined with the `has_component`
 function that is explained in the next section. For example::
 
     if esper.has_component(ent, SFX):
         sfx = esper.component_for_entity(ent, SFX)
         sfx.play()
 
-The *components_for_entity* function is a special function that returns ALL the Components that are
+The `components_for_entity` function is a special function that returns ALL the Components that are
 assigned to a specific Entity, as a tuple. This is a heavy operation, and not something you would
 want to do each frame or inside your `Processor.process` method. It can be useful, however, if
 you wanted to transfer all of a specific Entity's Components between two separate contexts
@@ -344,7 +368,7 @@ Let's look at the core part of the code::
         stun = esper.component_for_entity(ent, Stun)
         stun.duration -= dt
 
-This code works fine, but the *try_component* function can accomplish the same thing with one
+This code works fine, but the `try_component` function can accomplish the same thing with one
 less function call. The following example will get a specific Component if it exists, or
 return None if it does not::
 
@@ -362,12 +386,12 @@ functions even more concise ::
 More Examples
 -------------
 
-See the **/examples** folder to get an idea of how the basic structure of a game might look.
+See the `/examples` folder to get an idea of how the basic structure of a game might look.
 
 Event Dispatching
 =================
 
-Esper includes basic support for event dispatching and handling. This functionality is
+**esper** includes basic support for event dispatching and handling. This functionality is
 provided by three functions to set (register), remove, and dispatch events. Minimal error
 checking is done, so it's left up to the user to ensure correct naming and number of
 arguments are used when dispatching and receiving events.
@@ -397,7 +421,7 @@ Registered events and handlers are part of the current `World` context.
 Contributing
 ============
 
-Contributions to Esper are always welcome, but there are some specific project goals to keep in mind:
+Contributions to **esper** are always welcome, but there are some specific project goals to keep in mind:
 
 - Pure Python code only: no binary extensions, Cython, etc.
 - Try to target all non-EOL Python versions. Exceptions can be made if there is a compelling reason.

{esper-3.2 → esper-3.4}/README.md

@@ -2,12 +2,12 @@
 [![rtd](https://readthedocs.org/projects/esper/badge/?version=latest)](https://esper.readthedocs.io)
 [![PyTest](https://github.com/benmoran56/esper/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/benmoran56/esper/actions/workflows/unit-tests.yml)
 
-Esper is a lightweight Entity System module for Python, with a focus on performance
+esper is a lightweight Entity System module for Python, with a focus on performance
 ===================================================================================
 
-Esper is an MIT licensed Entity System, or, Entity Component System (ECS).
+**esper** is an MIT licensed Entity System, or, Entity Component System (ECS).
 The design is based on the Entity System concepts originally popularized by
-Adam Martin and others. The primary focus for esper is to maximize perfomance,
+Adam Martin and others. The primary focus for **esper** is to maximize perfomance,
 while handling most common use cases. 
 
 For more information on the ECS pattern, you might find the following
@@ -20,7 +20,7 @@ API documentation is hosted at ReadTheDocs: https://esper.readthedocs.io
 Due to the small size of the project, this README currently serves as general usage
 documentation.
 
-> :warning: **Esper 3.0 introduces breaking changes**. Version 3.0 removes the
+> :warning: **esper 3.0 introduces breaking changes**. Version 3.0 removes the
 > World object, and migrates its methods to module level functions. Multiple 
 > contexts can be created and switched between. The v2.x README can be found
 > here: https://github.com/benmoran56/esper/blob/v2_maintenance/README.md
@@ -41,15 +41,15 @@ documentation.
 
 Compatibility
 =============
-Esper attempts to target all currently supported Python releases (any Python version that is
-not EOL). Esper is written in 100% pure Python, so *any* compliant interpreter should work.
+**esper** attempts to target all currently supported Python releases (any Python version that is
+not EOL). **esper** is written in 100% pure Python, so *any* compliant interpreter should work.
 Automated testing is currently done for both CPython and PyPy3.
 
 
 Installation
 ============
-Esper is a pure Python package with no dependencies, so installation is flexible.
-You can simply copy the *esper* folder right into your project, and *import esper*.
+**esper** is a pure Python package with no dependencies, so installation is flexible.
+You can simply copy the `esper` folder right into your project, and `import esper`.
 You can also install into your site-packages from PyPi via `pip`::
 
     pip install --user --upgrade esper
@@ -64,8 +64,8 @@ Design
 
 * World Context
 
-Esper uses the concept of "World" contexts. When you first `import esper`, a default context is
-active. You create Entities, assign Components, register Processesors, etc., by calling functions
+**esper** uses the concept of "World" contexts. When you first `import esper`, a default context is
+active. You create Entities, assign Components, register Processors, etc., by calling functions
 on the `esper` module. Entities, Components and Processors can be created, assigned, or deleted
 while your game is running. A simple call to `esper.process()` is all that's needed for each
 iteration of your game loop. Advanced users can switch contexts, which can be useful for
@@ -74,18 +74,19 @@ isolating different game scenes that have different Processor requirements.
 
 * Entities 
 
-Entities are simple integer IDs (1, 2, 3, 4, etc.).
-Entities are "created", but they are generally not used directly. Instead, they are
-simply used as IDs in the internal Component database to track collections of Components.
-Creating an Entity is done with the `esper.create_entity()` function.
-
+Entities are defined internally as plain integer IDs (1, 2, 3, 4, etc.). Generally speaking
+you should not need to care about the individual entity IDs, since entities are queried based
+on their specific combination of Components - not by their ID. An Entity can be thought of as
+a specific combination of Components. Creating an Entity is done with the `esper.create_entity()`
+function. You can pass Component instances on creation or add/remove them later.
 
 * Components
 
-Components are defined as simple Python classes. In keeping with a pure Entity System
-design philosophy, they should not contain any logic. They might have initialization
-code or perhaps Python properties, but no processing logic whatsoever. A simple
-Component can be defined as::
+Components are defined as simple Python classes. In keeping with a pure Entity System design
+philosophy, Components should not contain any processing logic. They may contain initialization
+logic, and you can take advantage of Python language features, like properties, to simplify data
+lookup. The key point is that game logic does not belong in these classes, and Components should
+have no knowledge of other Components or Entities. A simple Component can be defined as::
 
     class Position:
         def __init__(self, x=0.0, y=0.0):
@@ -104,11 +105,26 @@ be repeated, and you can still instantiate the Component with positional or keyw
         x: float = 0.0
         y: float = 0.0
 
+Python language features, like properties, can be useful to simplify data access. For example,
+a Body component that is often repositioned may benefit from a local AABB (axis aligned bounding
+box) property::
+
+    @dataclass
+    class Body:
+        width:  int
+        height: int
+        pos_x:  float = 0
+        pos_y:  float = 0
+
+        @property
+        def aabb(self) -> tuple[float, float, float, float]:
+            return self.pos_x, self.pos_y, self.pos_x + self.width, self.pos_y + self.height
+
 
 * Processors
 
 Processors, also commonly known as "Systems", are where all processing logic is defined and executed.
-All Processors must inherit from the *esper.Processor* class, and have a method called *process*.
+All Processors must inherit from the `esper.Processor` class, and have a method called `process`.
 Other than that, there are no restrictions. You can define any additional methods you might need. 
 A simple Processor might look like::
 
@@ -119,21 +135,31 @@ A simple Processor might look like::
                 pos.x += vel.x
                 pos.y += vel.y
 
-In the above code, you can see the standard usage of the *esper.get_components()* function. This
+In the above code, you can see the standard usage of the `esper.get_components()` function. This
 function allows efficient iteration over all Entities that contain the specified Component types.
 This function can be used for querying two or more components at once. Note that tuple unpacking
-is necessary for the return component pairs: *(vel, pos)*.  In addition the Components, you also
-get a reference to the Entity ID (the *ent* object) for the current pair of Velocity/Position
-Components. This entity ID can be useful in a variety of cases. For example, if your Processor
-will need to delete certain Entites, you can call the *esper.delete_entity()* function on
-this Entity ID. Another common use is if you wish to add or remove a Component on this Entity
-as a result of some condition being met. 
+is necessary for the return component pairs: `(vel, pos)`.  In addition to Components, you also
+get a reference to the Entity ID for the current pair of Velocity/Position Components. This entity
+ID can be useful in a variety of cases. For example, if your Processor will need to delete certain
+Entites, you can call the `esper.delete_entity()` function on this Entity ID. Another common use
+is if you wish to add or remove a Component on this Entity as a result of some condition being met. 
+For example, an Entity that should be deleted once it's `Lifecycle` Component reaches 0::
+
+    class LifecycleProcessor(esper.Processor):
+        def __init__(self, ...):
+            ...
+    
+        def process(self, dt):
+            for ent, (life, rend) in esper.get_components(Lifecycle, Renderable):
+                life.lifespan -= dt
+                if life.lifespan <= 0:
+                    esper.delete_entity(ent)
 
 
 Quick Start
 ===========
 
-To get started, simply import esper::
+To get started, simply import **esper**::
 
     import esper
 
@@ -149,7 +175,7 @@ Optionally, Component instances can be assigned directly to the Entity on creati
 
 
 Design some Processors that operate on these Component types, and then register them with
-Esper for processing. You can specify an optional priority (higher numbers are processed first).
+**esper** for processing. You can specify an optional priority (higher numbers are processed first).
 All Processors are priority "0" by default::
 
     movement_processor = MovementProcessor()
@@ -162,18 +188,17 @@ All Processors are priority "0" by default::
     esper.add_processor(SomeProcessor())
 
 
-Executing all Processors is done with a single call to esper.process(). This will call the
+Executing all Processors is done with a single call to `esper.process()`. This will call the
 `process` method on all assigned Processors, in order of their priority. This is usually called
 once per frame update of your game (every tick of the clock).::
 
     esper.process()
 
 
-**Note:** You can pass any arguments (or keyword arguments) you need to *esper.process()*, but you
-must also make sure to receive them properly in the *process()* methods of your Processors. For
-example, if you pass a delta time argument as *esper.process(dt)*, your Processor's *process()*
-methods should all receive it as:
-*def process(self, dt):*
+**Note:** You can pass any arguments (or keyword arguments) you need to `esper.process()`, but you
+must also make sure to receive them properly in the `process()` methods of your Processors. For
+example, if you pass a delta time argument as `esper.process(dt)`, your Processor's `process()`
+methods should all receive it as: `def process(self, dt):`
 This is appropriate for libraries such as **pyglet**, which automatically pass a delta time value
 into scheduled functions.  
 
@@ -183,14 +208,13 @@ General Usage
 
 World Contexts
 --------------
-Esper has the capability of supporting multiple "World" contexts. On import, a "default" World is
+**esper** has the capability of supporting multiple "World" contexts. On import, a "default" World is
 active. All creation of Entities, assignment of Processors, and all other operations occur within
 the confines of the active World. In other words, the World contexts are completely isolated from
 each other. For basic games and designs, you may not need to bother with this functionality. A
 single default World context can often be enough. For advanced use cases, such as when different
 scenes in your game have different Entities and Processor requirements, this functionality can be
 quite useful. World context operations are done with the following functions::
-* 
 * esper.list_worlds()
 * esper.switch_world(name)
 * esper.delete_world(name)
@@ -202,7 +226,7 @@ delete the currently active World.
 Adding and Removing Processors
 ------------------------------
 You have already seen examples of adding Processors in an earlier section. There is also a
-*remove_processor* function available:
+`remove_processor` function available:
 
 * esper.add_processor(processor_instance)
 * esper.remove_processor(ProcessorClass)
@@ -218,10 +242,10 @@ remove Components inside your Processors. The following functions are available
 * esper.add_component(entity_id, component_instance)
 * esper.remove_component(entity_id, ComponentClass)
 
-As an example of this, you could have a "Blink" component with a *duration* attribute. This can be used
+As an example of this, you could have a "Blink" component with a `duration` attribute. This can be used
 to make certain things blink for s specific period of time, then disappear. For example, the code below
 shows a simplified case of adding this Component to an Entity when it takes damage in one processor. A 
-dedicated *BlinkProcessor* handles the effect, and then removes the Component after the duration expires::
+dedicated `BlinkProcessor` handles the effect, and then removes the Component after the duration expires::
 
     class BlinkComponent:
         def __init__(self, duration):
@@ -264,16 +288,16 @@ to it, the following functions are available:
 * esper.component_for_entity
 * esper.components_for_entity
 
-The *component_for_entity* function is useful in a limited number of cases where you know a specific
+The `component_for_entity` function is useful in a limited number of cases where you know a specific
 Entity ID, and wish to get a specific Component for it. An error is raised if the Component does not
-exist for the Entity ID, so it may be more useful when combined with the *has_component*
+exist for the Entity ID, so it may be more useful when combined with the `has_component`
 function that is explained in the next section. For example::
 
     if esper.has_component(ent, SFX):
         sfx = esper.component_for_entity(ent, SFX)
         sfx.play()
 
-The *components_for_entity* function is a special function that returns ALL the Components that are
+The `components_for_entity` function is a special function that returns ALL the Components that are
 assigned to a specific Entity, as a tuple. This is a heavy operation, and not something you would
 want to do each frame or inside your `Processor.process` method. It can be useful, however, if
 you wanted to transfer all of a specific Entity's Components between two separate contexts
@@ -334,7 +358,7 @@ Let's look at the core part of the code::
         stun = esper.component_for_entity(ent, Stun)
         stun.duration -= dt
 
-This code works fine, but the *try_component* function can accomplish the same thing with one
+This code works fine, but the `try_component` function can accomplish the same thing with one
 less function call. The following example will get a specific Component if it exists, or
 return None if it does not::
 
@@ -352,12 +376,12 @@ functions even more concise ::
 More Examples
 -------------
 
-See the **/examples** folder to get an idea of how the basic structure of a game might look.
+See the `/examples` folder to get an idea of how the basic structure of a game might look.
 
 Event Dispatching
 =================
 
-Esper includes basic support for event dispatching and handling. This functionality is
+**esper** includes basic support for event dispatching and handling. This functionality is
 provided by three functions to set (register), remove, and dispatch events. Minimal error
 checking is done, so it's left up to the user to ensure correct naming and number of
 arguments are used when dispatching and receiving events.
@@ -387,7 +411,7 @@ Registered events and handlers are part of the current `World` context.
 Contributing
 ============
 
-Contributions to Esper are always welcome, but there are some specific project goals to keep in mind:
+Contributions to **esper** are always welcome, but there are some specific project goals to keep in mind:
 
 - Pure Python code only: no binary extensions, Cython, etc.
 - Try to target all non-EOL Python versions. Exceptions can be made if there is a compelling reason.

{esper-3.2 → esper-3.4}/RELEASE_NOTES

@@ -1,3 +1,14 @@
+esper 3.3
+=========
+Maintenance release
+
+Changes
+-------
+- Fix unreadable `esper.current_world` property. (#100)
+- Minor typing configuration updates.
+- Remove outdated pyglet example. (Another one already exists).
+
+
 esper 3.2
 =========
 Maintenance release

{esper-3.2 → esper-3.4}/docs/index.rst

@@ -9,10 +9,28 @@ Processors
 Components
 ----------
 **esper** does not define any specific Component base class
-to inherit from. Instead, a normal Python class can be used.
-Also, while it's not required, the the `@dataclass` decorator
-from the `dataclasses` module can be useful to help write
-compact Component classes.
+to inherit from. Any valid Python class can be used. For more
+compact definitions, the ``@dataclass`` decorator from the
+``dataclasses`` module is quite useful. You can also use a
+``namedtuple`` instead of a class, but this is limited to
+cases where the Component's data does not need to be modified.
+Three examples of valid Components::
+
+    class Velocity:
+        def __init__(self, x=0.0, y=0.0, accel=0.1, decel=0.75, maximum=3):
+            self.vector = Vec2(x, y)
+            self.accel = accel
+            self.decel = decel
+            self.maximum = maximum
+
+
+    @dataclass
+    class Camera:
+        current_x_offset:   float = 0
+        current_y_offset:   float = 0
+
+
+    Interaction = namedtuple('Interaction', 'interaction_type target_name')
 
 
 The World context

{esper-3.2 → esper-3.4}/esper/__init__.py

@@ -23,7 +23,7 @@ from weakref import WeakMethod as _WeakMethod
 
 from itertools import count as _count
 
-__version__ = version = '3.2'
+__version__ = version = '3.4'
 
 
 ###################
@@ -81,10 +81,11 @@ def remove_handler(name: str, func: _Callable[..., None]) -> None:
     receive the named event, or if the named event does
     not exist, this function call will pass silently.
     """
-    if func not in event_registry.get(name, []):
+    func_ref = _ref(func)
+    if func_ref not in event_registry.get(name, []):
         return
 
-    event_registry[name].remove(func)
+    event_registry[name].remove(func_ref)
     if not event_registry[name]:
         del event_registry[name]
 
@@ -131,7 +132,7 @@ class Processor:
 #   ECS functions
 ###################
 
-_current_context: str = "default"
+_current_world: str = "default"
 _entity_count: "_count[int]" = _count(start=1)
 _components: _Dict[_Type[_Any], _Set[_Any]] = {}
 _entities: _Dict[int, _Dict[_Type[_Any], _Any]] = {}
@@ -139,10 +140,13 @@ _dead_entities: _Set[int] = set()
 _get_component_cache: _Dict[_Type[_Any], _List[_Any]] = {}
 _get_components_cache: _Dict[_Tuple[_Type[_Any], ...], _List[_Any]] = {}
 _processors: _List[Processor] = []
-process_times: _Dict[str, int] = {}
 event_registry: _Dict[str, _Any] = {}
+process_times: _Dict[str, int] = {}
+current_world: str = "default"
 
-# {context_name: (entity_count, components, entities, dead_entities, comp_cache, comps_cache, processors, process_times, event_registry)}
+
+# {context_name: (entity_count, components, entities, dead_entities,
+#                 comp_cache, comps_cache, processors, process_times, event_registry)}
 _context_map: _Dict[str, _Tuple[
     "_count[int]",
     _Dict[_Type[_Any], _Set[_Any]],
@@ -228,10 +232,10 @@ def get_processor(processor_type: _Type[Processor]) -> _Optional[Processor]:
 def create_entity(*components: _C) -> int:
     """Create a new Entity, with optional initial Components.
 
-    This funcion returns an Entity ID, which is a plain integer.
+    This function returns an Entity ID, which is a plain integer.
     You can optionally pass one or more Component instances to be
     assigned to the Entity on creation. Components can be also be
-    added later with the :py:func:`esper.add_component` funcion.
+    added later with the :py:func:`esper.add_component` function.
     """
     entity = next(_entity_count)
 
@@ -321,7 +325,8 @@ def has_component(entity: int, component_type: _Type[_C]) -> bool:
 
 def has_components(entity: int, *component_types: _Type[_C]) -> bool:
     """Check if an Entity has all the specified Component types."""
-    return all(comp_type in _entities[entity] for comp_type in component_types)
+    components_dict = _entities[entity]
+    return all(comp_type in components_dict for comp_type in component_types)
 
 
 def add_component(entity: int, component_instance: _C, type_alias: _Optional[_Type[_C]] = None) -> None:
@@ -387,9 +392,7 @@ def get_component(component_type: _Type[_C]) -> _List[_Tuple[int, _C]]:
     try:
         return _get_component_cache[component_type]
     except KeyError:
-        return _get_component_cache.setdefault(
-            component_type, list(_get_component(component_type))
-        )
+        return _get_component_cache.setdefault(component_type, list(_get_component(component_type)))
 
 
 @_overload
@@ -404,7 +407,7 @@ def get_components(__c1: _Type[_C], __c2: _Type[_C2], __c3: _Type[_C3]) -> _List
 
 @_overload
 def get_components(__c1: _Type[_C], __c2: _Type[_C2], __c3: _Type[_C3], __c4: _Type[_C4]) -> _List[
-    _Tuple[int, _Tuple[_C, _C2, _C3, _C4]]]:
+                   _Tuple[int, _Tuple[_C, _C2, _C3, _C4]]]:
     ...
 
 
@@ -413,9 +416,7 @@ def get_components(*component_types: _Type[_Any]) -> _Iterable[_Tuple[int, _Tupl
     try:
         return _get_components_cache[component_types]
     except KeyError:
-        return _get_components_cache.setdefault(
-            component_types, list(_get_components(*component_types))
-        )
+        return _get_components_cache.setdefault(component_types, list(_get_components(*component_types)))
 
 
 def try_component(entity: int, component_type: _Type[_C]) -> _Optional[_C]:
@@ -447,7 +448,7 @@ def try_components(entity: int, __c1: _Type[_C], __c2: _Type[_C2], __c3: _Type[_
 
 
 def try_components(entity: int, *component_types: _Type[_C]) -> _Optional[_Tuple[_C, ...]]:
-    """Try to get a multiple component types for an Entity.
+    """Try to get multiple component types for an Entity.
 
     This function will return the requested Components if they exist,
     or None if they do not. This allows a way to access optional Components
@@ -502,7 +503,8 @@ def timed_process(*args: _Any, **kwargs: _Any) -> None:
 
     This function is identical to :py:func:`esper.process`, but
     it additionally records the elapsed time of each processor
-    call (in milliseconds) in the`esper.process_times` dictionary.
+    (in milliseconds) in the :py:attr:`~process_times` dictionary
+    after each call.
     """
     clear_dead_entities()
     for processor in _processors:
@@ -525,7 +527,7 @@ def delete_world(name: str) -> None:
     Raises `PermissionError` if you attempt to delete the currently
     active World context.
     """
-    if _current_context == name:
+    if _current_world == name:
         raise PermissionError("The active World context cannot be deleted.")
 
     del _context_map[name]
@@ -537,20 +539,24 @@ def switch_world(name: str) -> None:
     Esper can have one or more "Worlds". Each World is a dedicated
     context, and does not share Entities, Components, events, etc.
     Some game designs can benefit from using a dedicated World
-    for each scene. For other designs, a single World may
-    be sufficient.
+    for each scene. For other designs, a single World may be sufficient.
 
     This function will allow you to create and switch between as
     many World contexts as required. If the requested name does not
     exist, a new context is created automatically with that name.
 
+    The name of the currently active World context can be checked
+    at any time by examining the :py:attr:`esper.current_world`.
+    This attribute gets updated whenever you switch Worlds, and
+    modifying it has no effect.
+
     .. note:: At startup, a "default" World context is active.
     """
     if name not in _context_map:
         # Create a new context if the name does not already exist:
         _context_map[name] = (_count(start=1), {}, {}, set(), {}, {}, [], {}, {})
 
-    global _current_context
+    global _current_world
     global _entity_count
     global _components
     global _entities
@@ -560,17 +566,9 @@ def switch_world(name: str) -> None:
     global _processors
     global process_times
     global event_registry
+    global current_world
 
     # switch the references to the objects in the named context_map:
     (_entity_count, _components, _entities, _dead_entities, _get_component_cache,
      _get_components_cache, _processors, process_times, event_registry) = _context_map[name]
-    _current_context = name
-
-
-@property   # type: ignore
-def current_world() -> str:
-    """The currently active World context.
-
-    To switch World contexts, see :py:func:`esper.switch_world`.
-    """
-    return _current_context
+    _current_world = current_world = name

{esper-3.2 → esper-3.4}/examples/pyglet_example.py

@@ -36,7 +36,7 @@ class MovementProcessor:
     def process(self, dt):
         # This will iterate over every Entity that has BOTH of these components:
         for ent, (vel, rend) in esper.get_components(Velocity, Renderable):
-            # Update the Renderable Component's position by it's Velocity:
+            # Update the Renderable Component's position by its Velocity:
             # An example of keeping the sprite inside screen boundaries. Basically,
             # adjust the position back inside screen boundaries if it is outside:
             new_x = max(self.minx, rend.sprite.x + vel.x)

{esper-3.2 → esper-3.4}/tests/test_world.py

@@ -505,6 +505,16 @@ def test_event_handler_switch_world():
     esper.dispatch_event("foo")
     assert called == 2
 
+def test_remove_handler():
+    def handler():
+        pass
+
+    assert esper.event_registry == {}
+    esper.set_handler("foo", handler)
+    assert "foo" in esper.event_registry
+    esper.remove_handler("foo", handler)
+    assert esper.event_registry == {}
+
 
 ##################################################
 #   Some helper functions and Component templates:

esper-3.2/.ruff.toml

@@ -1,3 +0,0 @@
-select = ["F", "E", "W", "C90", "B", "A", "C4", "G", "T20", "PT", "SLF", "TCH", "RET", "N", "ARG"]
-ignore = ["E501"]
-

esper-3.2/examples/pyglet_example_batch.py

@@ -1,245 +0,0 @@
-import pyglet
-from pyglet.gl import *
-from pyglet.window import key
-
-import esper
-
-
-FPS = 60
-RESOLUTION = 720, 480
-BGCOLOR = (0, 0, 0, 255)
-
-
-##################################
-#  Define some Components:
-##################################
-class Velocity:
-    def __init__(self, x=0.0, y=0.0):
-        self.x = x
-        self.y = y
-
-
-class Renderable:
-    def __init__(self, texture, width, height, posx, posy):
-        self.texture = texture
-        self._x = posx
-        self._y = posy
-        self.w = width
-        self.h = height
-        self.group = TextureBindGroup(texture)
-        self.vertex_list = None
-        self._dirty = True
-
-    @property
-    def x(self):
-        return self._x
-
-    @x.setter
-    def x(self, val):
-        if val != self._x:
-            self._x = val
-            self._dirty = True
-
-    @property
-    def y(self):
-        return self._y
-
-    @y.setter
-    def y(self, val):
-        if val != self._y:
-            self._y = val
-            self._dirty = True
-
-
-################################
-#  Define some Processors:
-################################
-class MovementProcessor:
-    def __init__(self, minx, miny, maxx, maxy):
-        super().__init__()
-        self.minx = minx
-        self.miny = miny
-        self.maxx = maxx
-        self.maxy = maxy
-
-    def process(self):
-        # This will iterate over every Entity that has BOTH of these components:
-        for ent, (vel, rend) in esper.get_components(Velocity, Renderable):
-            # Update the Renderable Component's position by it's Velocity:
-            rend.x += vel.x
-            rend.y += vel.y
-            # An example of keeping the sprite inside screen boundaries. Basically,
-            # adjust the position back inside screen boundaries if it tries to go outside:
-            rend.x = max(self.minx, rend.x)
-            rend.y = max(self.miny, rend.y)
-            rend.x = min(self.maxx - rend.w, rend.x)
-            rend.y = min(self.maxy - rend.h, rend.y)
-
-
-class TextureRenderProcessor():
-    def __init__(self, batch):
-        super().__init__()
-        self.batch = batch
-
-    def process(self):
-        # This will iterate over every Entity that has this Component, and
-        # add the texture associated with the Renderable Component instance
-        # and its vertice_list to the render batch. The batch will then be
-        # drawn by the 'on_draw' event handler of teh main window:
-        for entity, renderable in esper.get_component(Renderable):
-            self.draw_texture(renderable)
-
-    def draw_texture(self, renderable):
-        texture = renderable.texture
-
-        if renderable.vertex_list is None:
-            vertex_format = 'v2i/dynamic'
-            renderable.vertex_list = self.batch.add(4, GL_QUADS,
-                                                    renderable.group,
-                                                    vertex_format, 'c4B',
-                                                    ('t3f', texture.tex_coords))
-
-        if renderable._dirty:
-            x1 = renderable.x - texture.anchor_x
-            y1 = renderable.y - texture.anchor_y
-            x2 = x1 + texture.width
-            y2 = y1 + texture.height
-            renderable.vertex_list.vertices[:] = [x1, y1, x2, y1, x2, y2, x1, y2]
-            renderable.vertex_list.colors[:] = [255, 255, 255, 255] * 4
-            renderable._dirty = False
-
-
-############################################
-#  Some pyglet helper classes and functions:
-############################################
-def texture_from_image(image_name):
-    """Create a pyglet Texture from an image file"""
-    return pyglet.resource.image(image_name).get_texture()
-
-
-# Code below cobbled together from
-# https://pyglet.readthedocs.org/en/latest/programming_guide/graphics.html#hierarchical-state
-# and pyglet.sprite.SpriteGroup
-
-class TextureEnableGroup(pyglet.graphics.Group):
-    def set_state(self):
-        glEnable(GL_TEXTURE_2D)
-
-    def unset_state(self):
-        glDisable(GL_TEXTURE_2D)
-
-
-texture_enable_group = TextureEnableGroup()
-
-
-class TextureBindGroup(pyglet.graphics.Group):
-    def __init__(self, texture):
-        super().__init__(parent=texture_enable_group)
-        assert texture.target == GL_TEXTURE_2D
-        self.texture = texture
-        self.blend_src = GL_SRC_ALPHA
-        self.blend_dest = GL_ONE_MINUS_SRC_ALPHA
-
-    def set_state(self):
-        glBindTexture(GL_TEXTURE_2D, self.texture.id)
-        glPushAttrib(GL_COLOR_BUFFER_BIT)
-        glEnable(GL_BLEND)
-        glBlendFunc(self.blend_src, self.blend_dest)
-
-    def unset_state(self):
-        glPopAttrib()
-        glDisable(self.texture.target)
-
-    def __eq__(self, other):
-        return (other.__class__ is self.__class__ and
-                self.parent is other.parent and
-                self.texture.target == other.texture.target and
-                self.texture.id == other.texture.id and
-                self.blend_src == other.blend_src and
-                self.blend_dest == other.blend_dest)
-
-    def __hash__(self):
-        return hash((id(self.parent),
-                     self.texture.id, self.texture.target,
-                     self.blend_src, self.blend_dest))
-
-
-################################
-#  The main core of the program:
-################################
-def run(args=None):
-    # Initialize the main window stuff
-    window = pyglet.window.Window(width=RESOLUTION[0], height=RESOLUTION[1])
-    window.set_caption("Esper pyglet Example")
-    pyglet.gl.glClearColor(*BGCOLOR)
-    # pyglet graphics batch for efficient rendering
-    renderbatch = pyglet.graphics.Batch()
-
-    # Initialize Esper world, and create a "player" Entity with a few Components.
-    player = esper.create_entity()
-    esper.add_component(player, Velocity(x=0, y=0))
-    redsquare = Renderable(texture=texture_from_image("redsquare.png"),
-                           width=64,
-                           height=64,
-                           posx=100,
-                           posy=100)
-    esper.add_component(player, redsquare)
-
-    # Another motionless Entity:
-    enemy = esper.create_entity()
-    bluesquare = Renderable(texture=texture_from_image("bluesquare.png"),
-                            width=64,
-                            height=64,
-                            posx=400,
-                            posy=250)
-    esper.add_component(enemy, bluesquare)
-
-    # Create some Processor instances, and asign them to be processed.
-    render_processor = TextureRenderProcessor(batch=renderbatch)
-    movement_processor = MovementProcessor(minx=0, maxx=RESOLUTION[0], miny=0,
-                                           maxy=RESOLUTION[1])
-
-    @window.event
-    def on_key_press(symbol, modifiers):
-        if symbol == key.UP:
-            # Here is a way to directly access a specific Entity's Velocity
-            # Component's attribute (y) without making a temporary variable.
-            esper.component_for_entity(player, Velocity).y = 3
-        elif symbol == key.DOWN:
-            # For clarity, here is an alternate way in which a temporary variable
-            # is created and modified. The previous way above is recommended instead.
-            player_velocity_component = esper.component_for_entity(player, Velocity)
-            player_velocity_component.y = -3
-        elif symbol == key.LEFT:
-            esper.component_for_entity(player, Velocity).x = -3
-        elif symbol == key.RIGHT:
-            esper.component_for_entity(player, Velocity).x = 3
-        elif symbol == key.ESCAPE:
-            pyglet.app.exit()
-
-    @window.event
-    def on_key_release(symbol, modifiers):
-        if symbol in (key.UP, key.DOWN):
-            esper.component_for_entity(player, Velocity).y = 0
-        if symbol in (key.LEFT, key.RIGHT):
-            esper.component_for_entity(player, Velocity).x = 0
-
-    @window.event
-    def on_draw():
-        # Clear the window:
-        window.clear()
-        # Draw the batch of Renderables:
-        renderbatch.draw()
-
-    def update(dt):
-        # A single call to esper.process() will update all Processors:
-        render_processor.process()
-        movement_processor.process()
-
-    pyglet.clock.schedule_interval(update, 1.0 / FPS)
-    pyglet.app.run()
-
-
-if __name__ == "__main__":
-    import sys
-    sys.exit(run(sys.argv[1:]) or 0)