esper 3.1__tar.gz → 3.2__tar.gz

esper-3.2/.github/workflows/type-checking.yml

@@ -0,0 +1,25 @@
+name: type checking
+
+on:
+  push:
+  pull_request:
+
+
+jobs:
+  typechecking:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ 'ubuntu-latest', 'macos-latest', 'windows-latest' ]
+        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12-dev' ]
+    steps:
+      - name: Python ${{ matrix.python-version }} ${{ matrix.os }}
+        uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install mypy
+        run: pip install mypy
+      - name: Run mypy
+        run: mypy -v esper

{esper-3.1 → esper-3.2}/.github/workflows/unit-tests.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       matrix:
         os: [ 'ubuntu-latest', 'macos-latest', 'windows-latest' ]
-        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12-dev', 'pypy-3.7' ]
+        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12-dev', 'pypy-3.10' ]
     steps:
       - name: Python ${{ matrix.python-version }} ${{ matrix.os }}
         uses: actions/checkout@v3
@@ -23,20 +23,3 @@ jobs:
         run: pip install pytest
       - name: Run tests
         run: pytest -v tests
-  typechecking:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ 'ubuntu-latest', 'macos-latest', 'windows-latest' ]
-        python-version: [ '3.8', '3.9', '3.10', '3.11', '3.12-dev' ]
-    steps:
-      - name: Python ${{ matrix.python-version }} ${{ matrix.os }}
-        uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install mypy
-        run: pip install mypy
-      - name: Run mypy
-        run: mypy -v esper

{esper-3.1 → esper-3.2}/.mypy.ini

@@ -10,11 +10,11 @@ warn_unused_ignores = True
 warn_return_any = True
 no_implicit_reexport = True
 strict_equality = True
-strict_concatenate = True
+extra_checks = True
 
 [mypy-esper]
 disallow_untyped_defs = True
 disallow_untyped_calls = True
 
 [mypy-tests]
-check_untyped_defs = True
+check_untyped_defs = True

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: esper
-Version: 3.1
+Version: 3.2
 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
@@ -16,11 +16,14 @@ Esper is a lightweight Entity System module for Python, with a focus on performa
 ===================================================================================
 
 Esper is an MIT licensed Entity System, or, Entity Component System (ECS).
-The design is based on the Entity System concepts outlined by Adam Martin in his blog at
-http://t-machine.org/, and others. The primary focus is on keeping it as lightweight and
-performant as possible, while handling common use cases.
-
-The following Wikipedia article provides a summary of the ECS pattern:
+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,
+while handling most common use cases. 
+
+For more information on the ECS pattern, you might find the following
+resources interesting:
+https://github.com/SanderMertens/ecs-faq/blob/master/README.md
+https://github.com/jslee02/awesome-entity-component-system/blob/master/README.md
 https://en.wikipedia.org/wiki/Entity_component_system
 
 API documentation is hosted at ReadTheDocs: https://esper.readthedocs.io
@@ -48,22 +51,22 @@ documentation.
 
 Compatibility
 =============
-Esper attempts to target all currently supported Python releases (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.
+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 not strictly
-necessary. You can simply copy the *esper* folder into your project, and *import esper*.
-If you do want to install it into your site-packages, you can do so by using `setup.py`::
+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`::
 
-    python setup.py install --user
+    pip install --user --upgrade esper
 
-Or from PyPi via pip::
+Or from the source directory::
 
-    pip install --user --upgrade esper
+    pip install . --user
 
 
 Design
@@ -71,8 +74,8 @@ Design
 
 * World Context
 
-Esper uses the concept of "World" contexts. When you 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 Processesors, 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
@@ -91,14 +94,15 @@ Creating an Entity is done with the `esper.create_entity()` function.
 
 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, but no processing logic whatsoever. A simple Component can be defined as::
+code or perhaps Python properties, but no processing logic whatsoever. A simple
+Component can be defined as::
 
     class Position:
         def __init__(self, x=0.0, y=0.0):
             self.x = x
             self.y = y
 
-In addition, the excellent `dataclass` decorator is available in Python 3.7+.
+To save on typing, the standard library dataclass decorator is quite useful. 
 https://docs.python.org/3/library/dataclasses.html#module-dataclasses
 This decorator simplifies defining your Component classes. The attribute names don't need to
 be repeated, and you can still instantiate the Component with positional or keyword arguments::
@@ -190,19 +194,20 @@ General Usage
 World Contexts
 --------------
 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 operations exist within the
-confines of a World. For advanced use cases Esper allows you to switch between multiple Worlds,
-which are completely isolated from each other. This can be useful when different scenes in your
-game have different Entities and Processor requirements. World context operations are done with
-the following functions::
-
+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)
 
-When switching Worlds, be careful of the `name`. If a World doesn't exist, it will be created. 
-You can delete old Worlds which are no longer needed, but you cannot delete the currently active
-World.  
+When switching Worlds, be mindful of the `name`. If a World doesn't exist, it will be created when
+you first switch to it. You can delete old Worlds if they are no longer needed, but you can not
+delete the currently active World.  
 
 Adding and Removing Processors
 ------------------------------
@@ -396,8 +401,8 @@ Contributions to Esper are always welcome, but there are some specific project g
 
 - 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.
-- Avoid bloat as much as possible. New features will be considered if they are commonly useful. Generally speaking, we don't want to add functionality that is better handled in another module or library. 
-- Performance is preferrable to readability.
+- Avoid bloat as much as possible. New features will be considered if they are commonly useful. Generally speaking, we don't want to add functionality that is better served by another module or library. 
+- Performance is preferrable to readability. The public API should remain clean, but ugly internal code is acceptable if it provides a performance benefit. Every cycle counts! 
 
 If you have any questions before contributing, feel free to [open an issue].
 

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

@@ -6,11 +6,14 @@ Esper is a lightweight Entity System module for Python, with a focus on performa
 ===================================================================================
 
 Esper is an MIT licensed Entity System, or, Entity Component System (ECS).
-The design is based on the Entity System concepts outlined by Adam Martin in his blog at
-http://t-machine.org/, and others. The primary focus is on keeping it as lightweight and
-performant as possible, while handling common use cases.
-
-The following Wikipedia article provides a summary of the ECS pattern:
+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,
+while handling most common use cases. 
+
+For more information on the ECS pattern, you might find the following
+resources interesting:
+https://github.com/SanderMertens/ecs-faq/blob/master/README.md
+https://github.com/jslee02/awesome-entity-component-system/blob/master/README.md
 https://en.wikipedia.org/wiki/Entity_component_system
 
 API documentation is hosted at ReadTheDocs: https://esper.readthedocs.io
@@ -38,22 +41,22 @@ documentation.
 
 Compatibility
 =============
-Esper attempts to target all currently supported Python releases (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.
+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 not strictly
-necessary. You can simply copy the *esper* folder into your project, and *import esper*.
-If you do want to install it into your site-packages, you can do so by using `setup.py`::
+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`::
 
-    python setup.py install --user
+    pip install --user --upgrade esper
 
-Or from PyPi via pip::
+Or from the source directory::
 
-    pip install --user --upgrade esper
+    pip install . --user
 
 
 Design
@@ -61,8 +64,8 @@ Design
 
 * World Context
 
-Esper uses the concept of "World" contexts. When you 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 Processesors, 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
@@ -81,14 +84,15 @@ Creating an Entity is done with the `esper.create_entity()` function.
 
 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, but no processing logic whatsoever. A simple Component can be defined as::
+code or perhaps Python properties, but no processing logic whatsoever. A simple
+Component can be defined as::
 
     class Position:
         def __init__(self, x=0.0, y=0.0):
             self.x = x
             self.y = y
 
-In addition, the excellent `dataclass` decorator is available in Python 3.7+.
+To save on typing, the standard library dataclass decorator is quite useful. 
 https://docs.python.org/3/library/dataclasses.html#module-dataclasses
 This decorator simplifies defining your Component classes. The attribute names don't need to
 be repeated, and you can still instantiate the Component with positional or keyword arguments::
@@ -180,19 +184,20 @@ General Usage
 World Contexts
 --------------
 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 operations exist within the
-confines of a World. For advanced use cases Esper allows you to switch between multiple Worlds,
-which are completely isolated from each other. This can be useful when different scenes in your
-game have different Entities and Processor requirements. World context operations are done with
-the following functions::
-
+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)
 
-When switching Worlds, be careful of the `name`. If a World doesn't exist, it will be created. 
-You can delete old Worlds which are no longer needed, but you cannot delete the currently active
-World.  
+When switching Worlds, be mindful of the `name`. If a World doesn't exist, it will be created when
+you first switch to it. You can delete old Worlds if they are no longer needed, but you can not
+delete the currently active World.  
 
 Adding and Removing Processors
 ------------------------------
@@ -386,8 +391,8 @@ Contributions to Esper are always welcome, but there are some specific project g
 
 - 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.
-- Avoid bloat as much as possible. New features will be considered if they are commonly useful. Generally speaking, we don't want to add functionality that is better handled in another module or library. 
-- Performance is preferrable to readability.
+- Avoid bloat as much as possible. New features will be considered if they are commonly useful. Generally speaking, we don't want to add functionality that is better served by another module or library. 
+- Performance is preferrable to readability. The public API should remain clean, but ugly internal code is acceptable if it provides a performance benefit. Every cycle counts! 
 
 If you have any questions before contributing, feel free to [open an issue].
 

{esper-3.1 → esper-3.2}/RELEASE_NOTES

@@ -1,3 +1,13 @@
+esper 3.2
+=========
+Maintenance release
+
+Changes
+-------
+- Add `esper.current_world` property to easily check the current World context.
+- Made some minor docstring corrections, and added some programmer notes.
+
+
 esper 3.1
 =========
 Maintenance release

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

@@ -23,9 +23,7 @@ from weakref import WeakMethod as _WeakMethod
 
 from itertools import count as _count
 
-
-version = '3.1'
-__version__ = version
+__version__ = version = '3.2'
 
 
 ###################
@@ -50,6 +48,7 @@ def dispatch_event(name: str, *args: _Any) -> None:
 
 def _make_callback(name: str) -> _Callable[[_Any], None]:
     """Create an internal callback to remove dead handlers."""
+
     def callback(weak_method: _Any) -> None:
         event_registry[name].remove(weak_method)
         if not event_registry[name]:
@@ -106,23 +105,19 @@ class Processor:
 
     Processor instances must contain a `process` method, but you are otherwise
     free to define the class any way you wish. Processors should be instantiated,
-    and then added to a :py:class:`esper.World` instance by calling
-    :py:func:`esper.World.add_processor`. For example::
-
-        my_world = World()
+    and then added to the current World context by calling :py:func:`esper.add_processor`.
+    For example::
 
         my_processor_instance = MyProcessor()
-        my_world.add_processor(my_processor_instance)
+        esper.add_processor(my_processor_instance)
 
-    After adding your Processors to a :py:class:`esper.World`, Processor.world
-    will be set to the World it is in. This allows easy access to the World and
-    it's methods from your Processor methods. All Processors in a World will have
-    their `process` methods called by a single call to :py:func:`esper.World.process`,
-    so you will generally want to iterate over entities with one (or more) calls to
-    the appropriate world methods::
+     All the Processors that have been added to the World context will have their
+    :py:meth:`esper.Processor.process` methods called by a single call to
+    :py:func:`esper.process`. Inside the `process` method is generally where you
+    should iterate over Entities with one (or more) calls to the appropriate methods::
 
         def process(self):
-            for ent, (rend, vel) in self.world.get_components(Renderable, Velocity):
+            for ent, (rend, vel) in esper.get_components(Renderable, Velocity):
                 your_code_here()
     """
 
@@ -132,7 +127,6 @@ class Processor:
         raise NotImplementedError
 
 
-
 ###################
 #   ECS functions
 ###################
@@ -506,34 +500,33 @@ def process(*args: _Any, **kwargs: _Any) -> None:
 def timed_process(*args: _Any, **kwargs: _Any) -> None:
     """Track Processor execution time for benchmarking.
 
-    This function is identical to :py:func:`esper.process`,
-    but it will additionally record the elapsed time of each
-    processor call in the `esper.process_times` dictionary.
+    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.
     """
     clear_dead_entities()
     for processor in _processors:
         start_time = _time.process_time()
         processor.process(*args, **kwargs)
-        process_time = int(round((_time.process_time() - start_time) * 1000, 2))
-        process_times[processor.__class__.__name__] = process_time
+        process_times[processor.__class__.__name__] = int((_time.process_time() - start_time) * 1000)
 
 
 def list_worlds() -> _List[str]:
     """A list all World context names."""
-    return list(_context_map.keys())
+    return list(_context_map)
 
 
 def delete_world(name: str) -> None:
     """Delete a World context.
 
-    This will completely delete the World, including any entities
+    This will completely delete the World, including all entities
     that are contained within it.
 
-    Raises a NameError if you attempt to delete the currently
+    Raises `PermissionError` if you attempt to delete the currently
     active World context.
     """
     if _current_context == name:
-        raise NameError("Cannot delete active World context.")
+        raise PermissionError("The active World context cannot be deleted.")
 
     del _context_map[name]
 
@@ -542,19 +535,19 @@ def switch_world(name: str) -> None:
     """Switch to a new World context by name.
 
     Esper can have one or more "Worlds". Each World is a dedicated
-    context, and does not share Entities, Components, etc. For
-    some game designs, it simplifies things to use a dedicated
-    World 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.
-
-    .. note:: At startup, a "default" context exists, and is
-              already active.
+    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.
+
+    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.
+
+    .. note:: At startup, a "default" World context is active.
     """
     if name not in _context_map:
-        # Create a new
+        # Create a new context if the name does not already exist:
         _context_map[name] = (_count(start=1), {}, {}, set(), {}, {}, [], {}, {})
 
     global _current_context
@@ -568,6 +561,16 @@ def switch_world(name: str) -> None:
     global process_times
     global event_registry
 
+    # 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

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

@@ -275,14 +275,24 @@ def test_clear_dead_entities():
 
 
 def test_switch_world():
+    # The `create_entities` helper will add <number>/2 of
+    # 'ComponentA' to the World context. Make a new
+    # "left" context, and confirm this is True:
     esper.switch_world("left")
     assert len(esper.get_component(ComponentA)) == 0
     create_entities(200)
     assert len(esper.get_component(ComponentA)) == 100
+
+    # Switching to a new "right" World context, no
+    # 'ComponentA' Components should yet exist.
     esper.switch_world("right")
     assert len(esper.get_component(ComponentA)) == 0
     create_entities(300)
     assert len(esper.get_component(ComponentA)) == 150
+
+    # Switching back to the original "left" context,
+    # the original 100 Components should still exist.
+    # From there, 200 more should be added:
     esper.switch_world("left")
     assert len(esper.get_component(ComponentA)) == 100
     create_entities(400)
@@ -293,6 +303,16 @@ def test_switch_world():
 #   Some helper functions and Component templates:
 ##################################################
 def create_entities(number):
+    """This function will create X number of entities.
+
+    The entities are created with a mix of Components,
+    so the World context will see an addition of
+    ComponentA * number * 1
+    ComponentB * number * 1
+    ComponentC * number * 2
+    ComponentD * number * 1
+    ComponentE * number * 1
+    """
     for _ in range(number // 2):
         esper.create_entity(ComponentA(), ComponentB(), ComponentC())
         esper.create_entity(ComponentC(), ComponentD(), ComponentE())
@@ -459,17 +479,29 @@ def test_event_handler_switch_world():
     def handler():
         nonlocal called
         called += 1
+
+    # Switch to a new "left" World context, and register
+    # an event handler. Confirm that it is being called
+    # by checking that the 'called' variable is incremented.
     esper.switch_world("left")
     esper.set_handler("foo", handler)
     assert called == 0
     esper.dispatch_event("foo")
     assert called == 1
+
+    # Here we switch to a new "right" World context.
+    # The handler is registered to the "left" context only,
+    # so dispatching the event should have no effect. The
+    # handler is not attached, and so the 'called' value
+    # should not be incremented further.
     esper.switch_world("right")
-    assert called == 1
     esper.dispatch_event("foo")
     assert called == 1
+
+    # Switching back to the "left" context and dispatching
+    # the event, the handler should still be registered and
+    # the 'called' variable should be incremented by 1.
     esper.switch_world("left")
-    assert called == 1
     esper.dispatch_event("foo")
     assert called == 2