Reformat code with black

docs/scripts/gen_ref_nav.py

@@ -7,7 +7,9 @@
 
 pkg_name = "xpuz"
 nav = Nav()
-mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+mod_symbol = (
+    '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+)
 
 root = Path(__file__).parent.parent.parent
 src = root / "src"
@@ -35,7 +37,9 @@
         ident = ".".join(parts)
         fd.write(f"::: {ident}")
 
-    mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path.relative_to(root))
+    mkdocs_gen_files.set_edit_path(
+        full_doc_path, ".." / path.relative_to(root)
+    )
 
 with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
-    nav_file.writelines(nav.build_literate_nav())
+    nav_file.writelines(nav.build_literate_nav())

src/xpuz/__init__.py

@@ -1 +1 @@
-"""Play procedurally generated crosswords. Toplevel `__init__` module for `xpuz`."""
+"""Play procedurally generated crosswords. Toplevel `__init__` module for `xpuz`."""

src/xpuz/__main__.py

@@ -1,6 +1,7 @@
 """Entry point of ``xpuz``."""
 
 from configparser import ConfigParser
+
 try:
     from ctypes import windll
     from locale import windows_locale
@@ -17,7 +18,7 @@
 
 def _get_os_language() -> str:
     """Infer language code from operating system data.
-    
+
     Returns:
         The locale.
     """

src/xpuz/app/app.py

@@ -22,9 +22,9 @@
 
 def _app_process(**kwargs: Dict[str, Any]) -> None:
     """This function is executed as a new Process with the `multiprocessing`
-    module to ensure the web application does not block the execution of the 
+    module to ensure the web application does not block the execution of the
     Tkinter GUI.
-    
+
     Args:
         **kwargs: Jinja2 template and crossword-related data.
     """
@@ -62,10 +62,10 @@ def index() -> str:
 
 def _is_port_in_use(port: int) -> bool:
     """Check if `port` is in use.
-    
+
     Args:
         port: The port to check
-    
+
     Returns:
         Whether the port is in use or not.
     """
@@ -75,7 +75,7 @@ def _is_port_in_use(port: int) -> bool:
 
 def _create_app(**kwargs: Dict[str, Any]) -> None:
     """Execute the ``_app_process`` function as a multithreaded process.
-    
+
     Args:
         **kwargs: Jinja2 template and crossword-related data.
     """

src/xpuz/base.py

@@ -46,12 +46,15 @@ def _confirm_route(
         confirmation: Dict[str, bool] = {"close": True},
     ) -> bool:
         """Allow the user to confirm if they wish to route through a messagebox.
-        
+
         Args:
             action: A function to call if the user confirms to route.
             condition: Only perform the confirmation if `True`.
-            confirmation: Passed in `**kwargs` syntax to the [messagebox helper](utils.md#xpuz.utils.GUIHelper.confirm_with_messagebox)
-        
+            confirmation: Passed in `**kwargs` syntax to the 
+                [messagebox helper](
+                    utils.md#xpuz.utils.GUIHelper.confirm_with_messagebox
+                )
+
         Returns:
             The status of the route confirmation; whether it was accepted or not.
         """
@@ -79,13 +82,15 @@ def _route(
 
         All class instances that use ``_route`` must have their content packed
         and contain 4 content generation methods, as seen in the source code.
-        
+
         Args:
-            page_ref: The new page's name, used to retrieve the corresponding class from `locals()`.
+            page_ref: The new page's name, used to retrieve the corresponding 
+                      class from `locals()`.
             base: The main app instance.
             title: The new page's title.
-            **kwargs: Confirmation dictionary routed to [_confirm_route](base.md#xpuz.base.Addons._confirm_route).
-        
+            **kwargs: Confirmation dictionary routed to 
+                [_confirm_route](base.md#xpuz.base.Addons._confirm_route).
+
         Returns:
             Status of the route; whether it was performed or not.
         """
@@ -126,18 +131,24 @@ class Base(CTk, Addons):
     """The main app instance. Contains methods used by all pages."""
 
     base_container: CTkFrame = None
-    lang_info: Tuple[Dict[str, str], List[str]] = [] 
-    locale: Locale = None 
-    cfg: ConfigParser = None 
+    lang_info: Tuple[Dict[str, str], List[str]] = []
+    locale: Locale = None
+    cfg: ConfigParser = None
     fullscreen: bool = False
     page_inst: object = None
 
-    def __init__(self, **kwargs: Dict[str, Union[Tuple[Dict[str, str], List[str]], Locale, ConfigParser]]) -> None:
+    def __init__(
+        self,
+        **kwargs: Dict[
+            str, Union[Tuple[Dict[str, str], List[str]], Locale, ConfigParser]
+        ],
+    ) -> None:
         """Initialise the base instance and container and apply widget scaling,
         theme and appearance.
-        
+
         Args:
-            **kwargs: `lang_info`, `cfg`, and `locale` objects passed from [main](__main__.md#xpuz.__main__.main).
+            **kwargs: `lang_info`, `cfg`, and `locale` objects passed from 
+                [main](__main__.md#xpuz.__main__.main).
         """
         super().__init__()
 
@@ -167,8 +178,8 @@ def __init__(self, **kwargs: Dict[str, Union[Tuple[Dict[str, str], List[str]], L
 
     def _set_dim(self, dim: Tuple[int, int] = DIM) -> None:
         """Set the dimensions of the program during runtime.
-        
-        Args: 
+
+        Args:
             dim: The dimensions.
         """
         scale = float(Base.cfg.get("m", "scale"))
@@ -205,7 +216,7 @@ def _exit_handler(
         """Called when the event `WM_DELETE_WINDOW` occurs or when the the
         program must be restarted, in which case the ``restart`` default
         parameter is overridden.
-        
+
         Args:
             restart: Whether to perform a restart or not.
             webapp_on: Whether the `Flask` web app is running or not.

src/xpuz/constants.py

@@ -1,12 +1,49 @@
 """Constant values used across the source code, defining values such as paths
 and colour values for both the GUI and the web application.
 
-NOTE: You can view the attributes that do not belong to any classes in this module 
-by pressing the `View source of this page` to the left of the table of contents.
+Attributes:
+    DIR_PATH: Path to the toplevel of `xpuz`.
+    TEMPLATE_CFG_PATH: Path to template `config.ini` file.
+    DOC_PATH: Path to the system's documents directory or equivalent.
+    DOC_DATA_PATH: Path to the `xpuz` folder within the system's documents directory.
+    DOC_CAT_PATH: Path to the `user` folder within the `xpuz` folder.
+    DOC_CFG_PATH: Path to the `config.ini` file within the `xpuz` folder.
+    LOCALES_PATH: Path to the package's locales folder.
+    BASE_POT_PATH: Path to the package's translation template file.
+    ASSETS_PATH: Path to the package's `assets` folder.
+    IMAGES_PATH: Path to the package's `image` folder, located within `assets`. 
+    BASE_CWORDS_PATH: Path to the package's base crosswords folder.
+    ATTEMPTS_DB_PATH: Path to the `attempts_db.json` file for crossword optimisation.
+    DIFFICULTIES: Crossword difficulties.
+    ACROSS: Representation of a word going right to left.
+    DOWN: Representation of a word going top to bottom.
+    EMPTY: Representation of a void cell in the crossword grid.
+    NONLANGUAGE_PATTERN: Regex pattern to filter out non-language characters.
+    QUALITY_MAP: Mapping of crossword quality descriptors to a float value, 
+        which is used to scale how many optimisation attempts are undergone to 
+        make a crossword with that quality.
+    WHITESPACE_SCALAR: A value to scale the whitespace present in a crossword grid.
+    DIMENSIONS_CONSTANT: A value that is added to the final grid dimension
+        calculation after applying `math.ceil`.
+    PDF_WIDTH: PDF A4 width.
+    PDF_HEIGHT: PDF A4 height.
+    PDF_MARGIN: PDF A4 margin.
+    FONTSIZE_DIR_TITLE: Font size of the title for the 'Across' or 'Down'
+        columns in a PDF.
+    FONTSIZE_DEF: Clue font size.
+    PAGE_DEF_MAX: How many clues can fit on a page.
+    DIM: Standard tkinter GUI dimensions
+    EDITOR_DIM: Dimensions for the crossword editor within the tkinter GUI.
+    LANG_REPLACEMENTS: Mapping of google translate language codes to their
+        respective `Babel` language codes. `None` if they do not exist, otherwise,
+        a string representing the `Babel`-correct code.
+    
+    
+    
 """
 
 from os import path
-from pathlib import Path
+from pathlib import Path, PosixPath, WindowsPath
 from typing import Dict, List, Union
 
 from platformdirs import user_documents_dir
@@ -18,6 +55,7 @@ class Colour:
 
     class Global:
         """Global hex colours."""
+
         BUTTON: str = "#21528C"
         BUTTON_HOVER: str = "#13385F"
         EXIT_BUTTON: str = "#ED3B4D"
@@ -30,6 +68,7 @@ class Global:
 
     class Light:
         """Light mode hex colours."""
+
         MAIN: str = "#C7D0D4"
         SUB: str = "#DFE8ED"
         TEXT: str = "#242424"
@@ -41,6 +80,7 @@ class Light:
 
     class Dark:
         """Dark mode hex colours."""
+
         MAIN: str = "#263238"
         SUB: str = "#37474F"
         TEXT: str = "#D7D6D6"
@@ -52,39 +92,39 @@ class Dark:
 
 
 # Absolute paths used across the source code.
-DIR_PATH = Path(__file__).resolve().parents[0]
-TEMPLATE_CFG_PATH = path.join(DIR_PATH, "template.config.ini")
-DOC_PATH = user_documents_dir()
-DOC_DATA_PATH = path.join(DOC_PATH, "xpuz")
-DOC_CAT_PATH = path.join(DOC_DATA_PATH, "user")
-DOC_CFG_PATH = path.join(DOC_DATA_PATH, "config.ini")
-LOCALES_PATH = path.join(DIR_PATH, "locales")
-BASE_POT_PATH = path.join(LOCALES_PATH, "base.pot")
-ASSETS_PATH = path.join(DIR_PATH, "assets")
-IMAGES_PATH = path.join(ASSETS_PATH, "images")
-CWORD_IMG_LIGHT_PATH = path.join(IMAGES_PATH, "cword_light.png")
-CWORD_IMG_DARK_PATH = path.join(IMAGES_PATH, "cword_dark.png")
-FS_IMG_LIGHT_PATH = path.join(IMAGES_PATH, "fs_light.png")
-FS_IMG_DARK_PATH = path.join(IMAGES_PATH, "fs_dark.png")
-EXPORT_IMG_PATH = path.join(IMAGES_PATH, "export.png")
-IMPORT_IMG_PATH = path.join(IMAGES_PATH, "import.png")
-EXPORT_DIS_IMG_PATH = path.join(IMAGES_PATH, "export_dis.png")
-IMPORT_DIS_IMG_PATH = path.join(IMAGES_PATH, "import_dis.png")
-FOLDER_IMG_PATH = path.join(IMAGES_PATH, "folder.png")
-FOLDER_DIS_IMG_PATH = path.join(IMAGES_PATH, "folder_dis.png")
-WIN_LOGO_PATH = path.join(IMAGES_PATH, "logo.ico")
-LINUX_LOGO_PATH = "@" + path.join(IMAGES_PATH, "logo.xbm")
-BASE_CWORDS_PATH = path.join(DIR_PATH, "base_cwords")
-ATTEMPTS_DB_PATH = path.join(DIR_PATH, "data", "attempts_db.json")
+DIR_PATH: Union[PosixPath, WindowsPath] = Path(__file__).resolve().parents[0]
+TEMPLATE_CFG_PATH: str = path.join(DIR_PATH, "template.config.ini")
+DOC_PATH: str = user_documents_dir()
+DOC_DATA_PATH: str = path.join(DOC_PATH, "xpuz")
+DOC_CAT_PATH: str = path.join(DOC_DATA_PATH, "user")
+DOC_CFG_PATH: str = path.join(DOC_DATA_PATH, "config.ini")
+LOCALES_PATH: str = path.join(DIR_PATH, "locales")
+BASE_POT_PATH: str = path.join(LOCALES_PATH, "base.pot")
+ASSETS_PATH: str = path.join(DIR_PATH, "assets")
+IMAGES_PATH: str = path.join(ASSETS_PATH, "images")
+CWORD_IMG_LIGHT_PATH: str = path.join(IMAGES_PATH, "cword_light.png")
+CWORD_IMG_DARK_PATH: str = path.join(IMAGES_PATH, "cword_dark.png")
+FS_IMG_LIGHT_PATH: str = path.join(IMAGES_PATH, "fs_light.png")
+FS_IMG_DARK_PATH: str = path.join(IMAGES_PATH, "fs_dark.png")
+EXPORT_IMG_PATH: str = path.join(IMAGES_PATH, "export.png")
+IMPORT_IMG_PATH: str = path.join(IMAGES_PATH, "import.png")
+EXPORT_DIS_IMG_PATH: str = path.join(IMAGES_PATH, "export_dis.png")
+IMPORT_DIS_IMG_PATH: str = path.join(IMAGES_PATH, "import_dis.png")
+FOLDER_IMG_PATH: str = path.join(IMAGES_PATH, "folder.png")
+FOLDER_DIS_IMG_PATH: str = path.join(IMAGES_PATH, "folder_dis.png")
+WIN_LOGO_PATH: str = path.join(IMAGES_PATH, "logo.ico")
+LINUX_LOGO_PATH: str = "@" + path.join(IMAGES_PATH, "logo.xbm")
+BASE_CWORDS_PATH: str = path.join(DIR_PATH, "base_cwords")
+ATTEMPTS_DB_PATH: str = path.join(DIR_PATH, "data", "attempts_db.json")
 
 
 # Crossword-related constants.
 DIFFICULTIES: List[str] = ["Easy", "Medium", "Hard", "Extreme"]
 ACROSS: str = "ACROSS"
 DOWN: str = "DOWN"
-EMPTY: str = "\u25AE"
+EMPTY: str = "\u25ae"
 NONLANGUAGE_PATTERN: Pattern = compile(r"\PL")
-QUALITY_MAP: Dict[str, int] = {
+QUALITY_MAP: Dict[str, float] = {
     "terrible": 0.05,
     "poor": 0.25,
     "average": 0.5,
@@ -96,12 +136,12 @@ class Dark:
 
 
 # PDF-related constants
-PDF_WIDTH = 3508
-PDF_HEIGHT = 2480
-PDF_MARGIN = 150
-FONTSIZE_DIR_TITLE = 100
-FONTSIZE_DEF = 40
-PAGE_DEF_MAX = 25
+PDF_WIDTH: int = 3508
+PDF_HEIGHT: int = 2480
+PDF_MARGIN: int = 150
+FONTSIZE_DIR_TITLE: int = 100
+FONTSIZE_DEF: int = 40
+PAGE_DEF_MAX: int = 25
 
 
 # Base english strings
@@ -119,13 +159,13 @@ class Dark:
 
 
 # Misc constants
-PYPI_URL = "https://pypi.org/project/xpuz/"
-RELEASE_API_URL = (
+PYPI_URL: str = "https://pypi.org/project/xpuz/"
+RELEASE_API_URL: str = (
     "https://api.github.com/repos/tomasvana10/xpuz/releases/latest"
 )
-PROJECT_URL = "https://github.com/tomasvana10/xpuz"
-DIM = (900, 650)
-EDITOR_DIM = (1125, 600)
+PROJECT_URL: str = "https://github.com/tomasvana10/xpuz"
+DIM: Tuple[int, int] = (900, 650)
+EDITOR_DIM: Tuple[int, int] = (1125, 600)
 PAGE_MAP: Dict[str, str] = {
     "HomePage": "Crossword Puzzle",
     "BrowserPage": "Crossword Browser",
@@ -147,6 +187,6 @@ class Dark:
     "ku": None,
     "sd": None,
 }
-REVERSE_LANG_REPLACEMENTS = {
+REVERSE_LANG_REPLACEMENTS: Dict[Union[str, None], str] = {
     value: key for key, value in LANG_REPLACEMENTS.items()
 }