Merge pull request #167 from Chrezm/documentation

Documentation

Author: Chrezm

server/area_manager.py

@@ -48,8 +48,9 @@
 
 class AreaManager(AssetManager):
     """
-    Create a new manager for the areas in a server.
-    Contains the Area object definition, as well as the server's area list.
+    A manager for areas. Area managers store a list of areas either from a
+    loaded file or an adequate Python representation.
+    It also contains the Area object definition.
     """
 
     class Area:
@@ -1148,14 +1149,14 @@ def __init__(self, server: TsuserverDR):
         Parameters
         ----------
         server: TsuserverDR
-            The server this area belongs to.
+            The server this area manager belongs to.
         """
 
         super().__init__(server)
         self._areas = []
         self._source_file = 'config/areas.yaml'
         self.area_names = set()
-        self.load_areas()
+        self.load_file(self._source_file)
 
     @property
     def areas(self) -> List[Area]:
@@ -1165,28 +1166,92 @@ def areas(self) -> List[Area]:
         return self.get_areas()
 
     def get_name(self) -> str:
+        """
+        Return `'area list'`.
+
+        Returns
+        -------
+        str
+            `'area list'`.
+        """
+
         return 'area list'
 
     def get_default_file(self) -> str:
+        """
+        Return `'config/areas.yaml'`.
+
+        Returns
+        -------
+        str
+            `'config/areas.yaml'`.
+        """
+
         return 'config/areas.yaml'
 
     def get_loader(self) -> Callable[[str, ], str]:
-        return self.server.load_areas
+        """
+        Return `self.server.load_file`.
 
-    def get_areas(self) -> List[Area]:
-        return self._areas.copy()
+        Returns
+        -------
+        Callable[[str, ], str]
+            `self.server.load_file`.
+        """
+
+        return self.server.load_areas
 
     def get_source_file(self) -> Union[str, None]:
+        """
+        Return the source file of the last area list the manager successfully loaded relative to
+        the root directory of the server, or None if the latest loaded area list was loaded raw.
+
+        Returns
+        -------
+        Union[str, None]
+            Source file or None.
+        """
+
         return self._source_file
 
+    def get_custom_folder(self) -> str:
+        """
+        Return `'config/area_lists'`.
+
+        Returns
+        -------
+        str
+            `'config/area_lists'`.
+        """
+
+        return 'config/area_lists'
+
+    def get_areas(self) -> List[Area]:
+        """
+        Return a copy of the areas managed by this manager.
+
+        Returns
+        -------
+        List[Area]
+            Areas managed.
+        """
+
+        return self._areas.copy()
+
     def load_areas(self, area_list_file: str = 'config/areas.yaml') -> List[Area]:
+        Constants.warn_deprecated('area_manager.load_areas',
+                                  'area_manager.load_file',
+                                  '4.4')
+        return self.load_file(area_list_file)
+
+    def load_file(self, source_file: str) -> List:
         """
-        Load an area list.
+        Load an area list from a file.
 
         Parameters
         ----------
-        area_list_file: str, optional
-            Location of the area list to load. Defaults to 'config/areas.yaml'.
+        source_file: str
+            Location of the area list to load.
 
         Returns
         -------
@@ -1202,19 +1267,44 @@ def load_areas(self, area_list_file: str = 'config/areas.yaml') -> List[Area]:
         ServerError.YAMLInvalidError
             If the file was empty, had a YAML syntax error, or could not be decoded using UTF-8.
         ServerError.FileSyntaxError
-            If the file failed verification for its asset type.
+            If the file failed verification for areas.
         """
 
-        areas = ValidateAreas().validate(area_list_file, extra_parameters={
+        areas = ValidateAreas().validate(source_file, extra_parameters={
             'server_character_list': self.server.character_manager.get_characters(),
             'server_default_area_description': self.server.config['default_area_description']
             })
-        areas = self._load_areas(areas, area_list_file)
+        areas = self._load_areas(areas, source_file)
         self._check_structure()
 
         return areas
 
-    def load_areas_raw(self, yaml_contents: Dict) -> List[Area]:
+    def load_raw(self, yaml_contents: Dict) -> List[Area]:
+        """
+        Load an area list from a YAML representation.
+
+        Parameters
+        ----------
+        yaml_contents: Dict
+            YAML representation.
+
+        Returns
+        -------
+        List[AreaManager.Area]
+            Areas.
+
+        Raises
+        ------
+        ServerError.FileNotFoundError
+            If the file was not found.
+        ServerError.FileOSError
+            If there was an operating system error when opening the file.
+        ServerError.YAMLInvalidError
+            If the file was empty, had a YAML syntax error, or could not be decoded using UTF-8.
+        ServerError.FileSyntaxError
+            If the file failed verification for its asset type.
+        """
+
         areas = ValidateAreas().validate_contents(yaml_contents, extra_parameters={
             'server_character_list': self.server.character_manager.get_characters(),
             'server_default_area_description': self.server.config['default_area_description']
@@ -1446,5 +1536,16 @@ def change_passage_lock(self, client: ClientManager.Client,
 
         return now_reachable
 
-    def _check_structure(self) -> bool:
+    def _check_structure(self):
+        """
+        Assert that all invariants specified in the class description are maintained.
+
+        Raises
+        ------
+        AssertionError
+            If any of the invariants are not maintained.
+
+        """
+
+        # 1. At least one area.
         assert self._areas