Made exceptions raised from EntityDictionary.__missing__ easier to track and updated docstrings.

Author: jordanbriere

addons/source-python/packages/source-python/entities/dictionary.py

@@ -33,23 +33,42 @@ class EntityDictionary(AutoUnload, dict):
     """Helper class used to store entity instances."""
 
     def __init__(self, factory=Entity, *args, **kwargs):
-        """Initialize the dictionary."""
+        """Initializes the dictionary.
+
+        :param callable factory:
+            Factory class or function used to create missing instances. Set to
+            `None` to disable this feature.
+
+            Factory signature: index, *args, **kwargs
+        :param tuple args:
+            Arguments passed to the factory class or function.
+        :param dict kwargs:
+            Keyword arguments passed to the factory class or function.
+        """
         # Store the given entity class...
         self._factory = factory
 
         # Store given arguments/keywords
         self._args = args
         self._kwargs = kwargs
 
-        # Register our OnEntityDeleted listener...
+        # Register our networked entity deletion listener...
         on_networked_entity_deleted_listener_manager.register_listener(
             self._on_networked_entity_deleted)
 
         # Initialize the dictionary...
         super().__init__()
 
     def __missing__(self, index):
-        """Add and return the entity instance for the given index."""
+        """Called when an instance is requested but missing.
+
+        :param int index:
+            The index of the entity instance requested.
+
+        :raises KeyError:
+            If the auto-construction of missing instances is disabled or the
+            factory class or function fails to return an instance.
+        """
         # Get the factory
         factory = self._factory
 
@@ -61,7 +80,7 @@ def __missing__(self, index):
         try:
             instance = factory(index, *self._args, **self._kwargs)
         except Exception as e:
-            raise KeyError(str(e))
+            raise KeyError(e).with_traceback(e.__traceback__) from None
 
         # Only cache entities that are not marked for deletion.
         # This is required, because if someone request an entity instance
@@ -73,13 +92,17 @@ def __missing__(self, index):
         return instance
 
     def __delitem__(self, index):
-        """Remove the given index from the dictionary."""
+        """Removes the given index from the dictionary.
+
+        :param int index:
+            The index of the entity instance being removed.
+        """
         # Remove the given index from the dictionary...
         with suppress(KeyError):
             super().__delitem__(index)
 
     def from_inthandle(self, inthandle):
-        """Get an entity instance from an inthandle.
+        """Returns an entity instance from an inthandle.
         
         :param int inthandle:
             The inthandle.
@@ -88,7 +111,11 @@ def from_inthandle(self, inthandle):
         return self[index_from_inthandle(inthandle)]
 
     def on_automatically_removed(self, index):
-        """Called when an index is automatically removed."""
+        """Called when an index is automatically removed.
+
+        :param int index:
+            The index of the entity instance being removed.
+        """
 
     def _on_networked_entity_deleted(self, entity):
         """Internal networked entity deletion callback.

addons/source-python/packages/source-python/players/dictionary.py

@@ -27,11 +27,22 @@ class PlayerDictionary(EntityDictionary):
     """Helper class used to store player instances."""
 
     def __init__(self, factory=Player, *args, **kwargs):
-        """Initialize the dictionary."""
+        """Initializes the dictionary.
+
+        :param callable factory:
+            Factory class or function used to create missing instances. Set to
+            `None` to disable this feature.
+
+            Factory signature: index, *args, **kwargs
+        :param tuple args:
+            Arguments passed to the factory class or function.
+        :param dict kwargs:
+            Keyword arguments passed to the factory class or function.
+        """
         super().__init__(factory, *args, **kwargs)
 
     def from_userid(self, userid):
-        """Get a player instance from a userid.
+        """Returns a player instance from a userid.
         
         :param int userid: The userid.
         :rtype: Player

addons/source-python/packages/source-python/weapons/dictionary.py

@@ -26,5 +26,16 @@ class WeaponDictionary(EntityDictionary):
     """Helper class used to store weapon instances."""
 
     def __init__(self, factory=Weapon, *args, **kwargs):
-        """Initialize the dictionary."""
+        """Initializes the dictionary.
+
+        :param callable factory:
+            Factory class or function used to create missing instances. Set to
+            `None` to disable this feature.
+
+            Factory signature: index, *args, **kwargs
+        :param tuple args:
+            Arguments passed to the factory class or function.
+        :param dict kwargs:
+            Keyword arguments passed to the factory class or function.
+        """
         super().__init__(factory, *args, **kwargs)