Large Docs update

.libcst.codemod.yaml

@@ -0,0 +1,17 @@
+# String that LibCST should look for in code which indicates that the
+# module is generated code.
+generated_code_marker: '@generated'
+# Command line and arguments for invoking a code formatter. Anything
+# specified here must be capable of taking code via stdin and returning
+# formatted code via stdout.
+formatter: ['black', '-']
+# List of regex patterns which LibCST will evaluate against filenames to
+# determine if the module should be touched.
+blacklist_patterns: []
+# List of modules that contain codemods inside of them.
+modules:
+- 'libcst.codemod.commands'- 'autotyping'
+# Absolute or relative path of the repository root, used for providing
+# full-repo metadata. Relative paths should be specified with this file
+# location as the base.
+repo_root: '.'

doc_scripts/griffe_extension.py

@@ -0,0 +1,36 @@
+import ast
+import re
+
+from griffe import Extension, Object, ObjectNode
+
+
+class RegexUrl(Extension):
+    IGNORE = ["sg"]  #
+
+    def regex_replace(self, input_string: str, regex_pattern, prefix: str):
+        compiled_pattern = re.compile(regex_pattern)
+
+        def replace_function(match):
+            parts = match.group(1).split(".")
+            if any(parts[0].startswith(prefix) for prefix in self.IGNORE):
+                return match.group(0)
+
+            # get text section of url, we will only use the last obj
+            text = parts[-1]
+
+            fn_suffix = ""
+            if match.group(2):
+                # pass () as html encoding
+                fn_suffix = "()"
+            complete_path = prefix + match.group(1)
+            return f"[{text}{fn_suffix}][{complete_path}]"
+
+        return compiled_pattern.sub(replace_function, input_string)
+
+    def on_instance(self, node: ast.AST | ObjectNode, obj: Object) -> None:
+        if obj.docstring:
+            # regex pattern matches a valid non-private class name or function, with or without a '()' at the end
+            regex_pattern = r"\`([A-Za-z][A-Za-z0-9_.]*)(\(\))*\`"
+            obj.docstring.value = self.regex_replace(
+                obj.docstring.value, regex_pattern, "pysimplesql.pysimplesql."
+            )

docs/index.md

@@ -1,17 +1,5 @@
-# Welcome to MkDocs
+# API Reference (more pages to come)
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
-
-## Commands
-
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
-
-## Project layout
-
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+::: pysimplesql.pysimplesql
+    options:
+      members_order: source

examples/MSAccess_examples/install_java.py

@@ -25,7 +25,7 @@
 # -------------------------------------------------
 # ROUTINES TO INSTALL JAVA IF USER DOES NOT HAVE IT
 # -------------------------------------------------
-def _is_java_installed():
+def _is_java_installed() -> bool:
     if "JAVA_HOME" in os.environ:
         return True
     previous_jre = load_setting("General", "java_home")
@@ -91,7 +91,7 @@ def java_check_install() -> bool:
     return True
 
 
-def save_setting(section: str, key: str, value: str):
+def save_setting(section: str, key: str, value: str) -> None:
     config = configparser.ConfigParser()
     config.read(SETTINGS_FILE)
 

examples/SQLite_examples/address_book.py

@@ -9,7 +9,7 @@
 
 
 # Zip code validation
-def validate_zip():
+def validate_zip() -> bool:
     zipcode = win['Addresses.zip'].get()
     if len(zipcode) != 5:
         sg.popup('Check your zip code and try again!', title="Zip code validation failed!")
@@ -97,7 +97,7 @@ def validate_zip():
     [sg.Text("Zip:"+" "*63), ss.field("Addresses.zip", size=(6, 1), no_label=True)],
     [ss.actions("Addresses", edit_protect=False, duplicate=True)],
     # sg.StatusBar sets character limit based on initial value. Here we are filling it with 100 spaces.
-    [sg.StatusBar(" " * 100, key="info_msg", metadata={"type": ss.TYPE_INFO})]
+    [sg.StatusBar(" " * 100, key="info_msg", metadata={"type": ss.ElementType.INFO})]
 
 ]
 win = sg.Window('Address book example', layout, finalize=True, ttk_theme=ss.themepack.ttk_theme)

examples/SQLite_examples/image_store.py

@@ -22,7 +22,7 @@
 # Note in the code later in this file, that you can choose to either:
 # 1) thumbnail the image prior to saving, so that you never store a large image in the database
 # 2) thumbnail the image only for display purposes, storing the full resolution image in the database
-def thumbnail(image_data, size=(320, 240)):
+def thumbnail(image_data, size: int=(320, 240)):
     img = Image.open(BytesIO(image_data))
     img.thumbnail(size)
     with BytesIO() as output:
@@ -72,7 +72,7 @@ def thumbnail(image_data, size=(320, 240)):
 # Another callback to update the sg.Image element when the elements update
 
 # first callback for encoding before saving to the database
-def encode_image():
+def encode_image() -> bool:
     if not win['image_path'].get():
         return False
     with open(win['image_path'].get(), 'rb') as file:
@@ -89,7 +89,7 @@ def encode_image():
 
 
 # Second callback updates the sg.Image element with the image data
-def update_display(frm: ss.Form, win: sg.Window):
+def update_display(frm: ss.Form, win: sg.Window) -> None:
     # Handle case where there are no records
     visible = len(frm["Image"].rows) == 0
     win['no_records'].update(visible=visible)

examples/SQLite_examples/orders.py

@@ -38,7 +38,7 @@
 # create your own validator to be passed to a
 # frm[DATA_KEY].column_info[COLUMN_NAME].custom_validate_fn
 # used below in the quick_editor arguments
-def is_valid_email(email):
+def is_valid_email(email: str):
     valid_email = re.match(r"^[\w\.-]+@[\w\.-]+\.\w+$", email) is not None
     if not valid_email:
         return ss.ValidateResponse(
@@ -268,7 +268,7 @@ def is_valid_email(email):
     [ss.field("order_details.price", sg.Text)],
     [ss.field("order_details.subtotal", sg.Text)],
     [sg.Sizer(h_pixels=0, v_pixels=10)],
-    [sg.StatusBar(" " * 100, key="info_msg", metadata={"type": ss.TYPE_INFO})],
+    [sg.StatusBar(" " * 100, key="info_msg", metadata={"type": ss.ElementType.INFO})],
 ]
 
 layout.append([sg.Frame("Order Details", orderdetails_layout, expand_x=True)])
@@ -308,7 +308,7 @@ def is_valid_email(email):
 # Application-side code to update orders `total`
 # when saving/deleting order_details line item
 # ----------------------------------------------
-def update_orders(frm_reference, window, data_key):
+def update_orders(frm_reference, window, data_key) -> bool:
     if data_key == "order_details":
         order_id = frm["order_details"]["order_id"]
         driver.execute(

examples/orders_multiple_databases.py

@@ -87,12 +87,12 @@
 
 
 class SqlFormat(dict):
-    def __missing__(self, key):
+    def __missing__(self, key) -> str:
         return ""
 
 
 class Template:
-    def __init__(self, template_string):
+    def __init__(self, template_string: str) -> None:
         self.template_string = template_string
 
     def render(self, context):
@@ -103,7 +103,7 @@ def render(self, context):
 # create your own validator to be passed to a
 # frm[DATA_KEY].column_info[COLUMN_NAME].custom_validate_fn
 # used below in the quick_editor arguments
-def is_valid_email(email):
+def is_valid_email(email: str):
     valid_email = re.match(r"^[\w\.-]+@[\w\.-]+\.\w+$", email) is not None
     if not valid_email:
         return ss.ValidateResponse(
@@ -476,7 +476,7 @@ def is_valid_email(email):
     [ss.field("order_details.price", sg.Text)],
     [ss.field("order_details.subtotal", sg.Text)],
     [sg.Sizer(h_pixels=0, v_pixels=10)],
-    [sg.StatusBar(" " * 100, key="info_msg", metadata={"type": ss.TYPE_INFO})],
+    [sg.StatusBar(" " * 100, key="info_msg", metadata={"type": ss.ElementType.INFO})],
 ]
 
 layout.append([sg.Frame("Order Details", orderdetails_layout, expand_x=True)])
@@ -555,7 +555,7 @@ def is_valid_email(email):
 # Application-side code to update orders `total`
 # when saving/deleting order_details line item
 # ----------------------------------------------
-def update_orders(frm_reference, window, data_key):
+def update_orders(frm_reference, window, data_key) -> bool:
     if data_key == "order_details":
         order_id = frm["order_details"]["order_id"]
         driver.execute(

examples/tutorial_files/Journal/v4/journal.py

@@ -63,7 +63,7 @@
 # ---------------
 # DATA VALIDATION
 # ---------------
-def cb_validate():
+def cb_validate() -> bool:
     date=win['Journal.entry_date'].Get()
     if date[4] == '-' and date[7]=='-' and len(date)==10:   # Make sure the date is 10 digits and has two dashes in the right place
         if str.isdigit(date[:4]):                           # Make sure the first 4 digits represent a year

mkdocs.yml

@@ -12,7 +12,6 @@ theme:
 
 nav:
     - Home: index.md
-    - API: api.md
 
 markdown_extensions:
     - admonition
@@ -30,4 +29,8 @@ plugins:
           domains: [std, py]
         options:
           docstring_style: "google"
-
+          docstring_options:
+            ignore_init_summary: true
+          merge_init_into_class: true
+          extensions:
+          - doc_scripts/griffe_extension.py:RegexUrl

pysimplesql/__init__.py

@@ -1,5 +1,4 @@
-"""
-Write data-driven desktop apps fast! Lightweight Python library supports SQLite,
+"""Write data-driven desktop apps fast! Lightweight Python library supports SQLite,
 MySQL/MariaDB, PostgreSQL & Flatfile CSV. Uses PySimpleGUI layouts.
 """
 

pysimplesql/docker_utils.py

@@ -1,5 +1,4 @@
-"""
-DOCKER UTILITIES
+"""DOCKER UTILITIES.
 
 This file is not used for pysimplesql base installation. It exists only as a collection
 of utility functions for examples which provide databases in Docker containers for
@@ -18,8 +17,7 @@
 
 
 def docker_image_installed(image: str) -> bool:
-    """
-    Check if the specified Docker image is installed locally.
+    """Check if the specified Docker image is installed locally.
 
     :param image: The Docker image, including the tag ("pysimplesql/examples:postgres")
     :return: True if the image is installed, False otherwise
@@ -35,8 +33,7 @@ def docker_image_installed(image: str) -> bool:
 
 
 def docker_image_is_latest(image: str) -> bool:
-    """
-    Check if a new version of a Docker image is available for download.
+    """Check if a new version of a Docker image is available for download.
 
     :param image: The Docker image, including the tag ("pysimplesql/examples:postgres")
     :return: True if a newer version is available, False otherwise
@@ -55,8 +52,7 @@ def docker_image_is_latest(image: str) -> bool:
 
 
 def docker_image_pull(image: str, latest: bool = True) -> None:
-    """
-    Pull the supplied docker image, displaying a progress bar.
+    """Pull the supplied docker image, displaying a progress bar.
 
     :param latest: Ensure that the latest docker image is used (updates the local image)
     :return:
@@ -106,8 +102,7 @@ def docker_image_pull(image: str, latest: bool = True) -> None:
 def docker_container_start(
     image: str, container_name: str, ports: dict
 ) -> docker.models.containers.Container:
-    """
-    Create and/or start a Docker container with the specified image and container name.
+    """Create and/or start a Docker container with the specified image/container name.
 
     :param image: The Docker image to use for the container
     :param container_name: The name to use for the container

pysimplesql/language_pack.py

@@ -1,5 +1,4 @@
-"""
-ChatGPT prompt:
+r"""ChatGPT prompt:
 I'm working on language localization for my python application.
 Can you look at this dict and make a spanish version?
 Please keep strings in brackets {} unaltered.