Improving documentation

.github/release-drafter.yml

@@ -1,8 +1,14 @@
 # name-template: 'v$RESOLVED_VERSION'
 # tag-template: 'v$RESOLVED_VERSION'
+header: |
+  ![DSG Logo](/images/devsetgo_lib_logo_white_bg.svg)
+  Drafts your next release notes as pull requests are merged into master.
+version-template: "2023.10.06.$PATCH"
 template: |
   #### What's Changed
   $CHANGES
+footer: |
+  Built with Probot using calendar versioning (year.month.day.build).
 categories:
   - title: 'Breaking'
     label: 'type: breaking'
@@ -16,18 +22,5 @@ categories:
     label: 'type: docs'
   - title: 'Dependency Updates'
     label: 'type: dependencies'
-
-version-resolver:
-  major:
-    labels:
-      - 'type: breaking'
-  minor:
-    labels:
-      - 'type: feature'
-  patch:
-    labels:
-      - 'type: bug'
-      - 'type: maintenance'
-      - 'type: docs'
-      - 'type: dependencies'
-      - 'type: security'
+  - title: 'Enhancements'
+    label: 'type: enhancement'

.github/workflows/pythonpublish.yml

@@ -51,6 +51,9 @@ jobs:
       - name: Generate changelog
         run: python3 scripts/changelog.py
 
+      - name: Create Examples documentation
+        run: python3 scripts/update_docs.py
+
       - name: Build MkDocs site
         run: mkdocs build
 

.github/workflows/release-drafter.yaml

@@ -19,6 +19,7 @@ permissions:
 
 jobs:
   update_release_draft:
+    concurrency: release-drafter
     permissions:
       # write permission is required to create a github release
       contents: write
@@ -33,7 +34,7 @@ jobs:
       #    echo "GHE_HOST=${GITHUB_SERVER_URL##https:\/\/}" >> $GITHUB_ENV
 
       # Drafts your next Release notes as Pull Requests are merged into "master"
-      - uses: release-drafter/release-drafter@master
+      - uses: release-drafter/release-drafter@v6.1.0
         # (Optional) specify config name to use, relative to .github/. Default: release-drafter.yml
         # with:
         #   config-name: my-config.yml

.github/workflows/sonarcloud.yml

@@ -13,8 +13,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
-      - name: SonarCloud Scan
-        uses: SonarSource/sonarcloud-github-action@master
+      - name: SonarQube Scan
+        uses: SonarSource/sonarqube-scan-action@v5.1.0
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

README.md

@@ -7,10 +7,10 @@ Python:
 
 Support Python Versions
 
-![Static Badge](https://img.shields.io/badge/Python-3.12%20%7C%203.11%20%7C%203.10%20%7C%203.9-blue)
+![Static Badge](https://img.shields.io/badge/Python-3.13%20%7C%203.12%20%7C%203.11%20%7C%203.10%20%7C%203.9-blue)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-[![Coverage Status](./coverage-badge.svg?dummy=8484744)](./reports/coverage/index.html)
-[![Tests Status](./tests-badge.svg?dummy=8484744)](./reports/coverage/index.html)
+[![Coverage Status](https://raw.githubusercontent.com/devsetgo/devsetgo_lib/refs/heads/dev/coverage-badge.svg)](./reports/coverage/index.html)
+[![Tests Status](https://raw.githubusercontent.com/devsetgo/devsetgo_lib/refs/heads/dev/tests-badge.svg)](./reports/coverage/index.html)
 
 CI/CD Pipeline:
 
@@ -29,6 +29,7 @@ SonarCloud:
 
 # DevSetGo Common Library
 
+![DSG Logo](/images/devsetgo_lib_logo_white_bg.svg)
 `devsetgo_lib` is a versatile library designed to provide common functions for Python applications. Its main goal is to increase reusability and reduce the need to rewrite the same functions across multiple applications. This also allows for quick defect resolution and propagation of fixes across all dependent projects.
 
 Read the Full Documentation [here](https://devsetgo.github.io/devsetgo_lib/).
@@ -40,6 +41,9 @@ Read the Full Documentation [here](https://devsetgo.github.io/devsetgo_lib/).
     - **CSV, JSON, and Text File Functions**: Create, read, write, and manipulate various file types with ease.
     - **Folder Functions**: Create and remove directories, list directory contents, and manage file system operations efficiently.
 
+  - **File Moving**:
+    Move files from one directory to another, with an option to compress the file being moved.
+
   - **Logging**:
     Comprehensive logging setup using the [Loguru Library]('https://loguru.readthedocs.io/en/stable/overview.html'). Provides extensive customization options for log configuration, including log rotation, retention, and formatting. Includes improvements for multiprocessing environments to ensure log messages are handled correctly across multiple processes.
 
@@ -58,6 +62,14 @@ Read the Full Documentation [here](https://devsetgo.github.io/devsetgo_lib/).
   - Configuration and management of asynchronous database sessions.
   - CRUD operations with async support.
 
+## Quick Reference
+
+- Logging & Config Setup
+- FastAPI Endpoints
+- Calendar & Date Utilities
+- Pattern Matching
+- CSV & JSON Helpers
+
 ---
 ## Installation
 

coverage.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" ?>
-<coverage version="7.7.1" timestamp="1743900473008" lines-valid="837" lines-covered="830" line-rate="0.9916" branches-covered="0" branches-valid="0" branch-rate="0" complexity="0">
+<coverage version="7.7.1" timestamp="1744421777684" lines-valid="837" lines-covered="830" line-rate="0.9916" branches-covered="0" branches-valid="0" branch-rate="0" complexity="0">
 	<!-- Generated by coverage.py: https://coverage.readthedocs.io/en/7.7.1 -->
 	<!-- Based on https://raw.githubusercontent.com/cobertura/web/master/htdocs/xml/coverage-04.dtd -->
 	<sources>

docs/examples/cal_example.md

@@ -0,0 +1,114 @@
+# cal_example Example
+
+# Overview
+
+This module demonstrates the usage of the `calendar_functions` module from the `dsg_lib.common_functions` package.
+It provides examples of how to work with months, both by their numeric representation and their names.
+
+The module includes two main functions:
+
+1. **`calendar_check_number`**:
+   - Iterates through a predefined list of month numbers (`month_list`) and uses the `get_month` function from `calendar_functions` to retrieve the corresponding month name.
+   - It then prints the result for each number in the list.
+   - Example:
+     - Input: `1`
+     - Output: `"January"`
+     - Input: `13` (invalid)
+     - Output: Depends on the implementation of `get_month` (e.g., `"Invalid Month"`).
+
+2. **`calendar_check_name`**:
+   - Iterates through a predefined list of month names (`month_names`) and uses the `get_month_number` function from `calendar_functions` to retrieve the corresponding numeric representation of the month.
+   - It then prints the result for each name in the list.
+   - Example:
+     - Input: `"january"`
+     - Output: `1`
+     - Input: `"bob"` (invalid)
+     - Output: Depends on the implementation of `get_month_number` (e.g., `"Invalid Month Name"`).
+
+# Features
+
+- **Validation of Inputs**:
+  The module demonstrates how to handle invalid inputs, such as:
+  - Numbers outside the valid range of months (1-12).
+  - Invalid month names that do not correspond to any recognized month.
+
+- **Testing and Debugging**:
+  This module can be used to test and validate the robustness of the `calendar_functions` module by providing a variety of valid and invalid inputs.
+
+# Usage
+
+- Run the script directly to see the output of the two functions.
+- Modify the `month_list` or `month_names` variables to test with different inputs.
+
+# Dependencies
+
+- **`dsg_lib.common_functions.calendar_functions`**:
+  - This module must be available and contain the following functions:
+    1. `get_month`: Accepts a numeric month (e.g., `1`) and returns the corresponding month name (e.g., `"January"`).
+    2. `get_month_number`: Accepts a month name (e.g., `"january"`) and returns the corresponding numeric representation (e.g., `1`).
+
+# Example Output
+
+## For `calendar_check_number`:
+If `month_list = [0, 1, 2, 3, 13]`, the output might be:
+```
+Invalid Month
+January
+February
+March
+Invalid Month
+```
+
+## For `calendar_check_name`:
+If `month_names = ["january", "february", "bob"]`, the output might be:
+```
+1
+2
+Invalid Month Name
+```
+
+# Notes
+
+- Ensure that the `calendar_functions` module is correctly implemented and imported.
+- The behavior for invalid inputs depends on the implementation of `get_month` and `get_month_number`.
+
+## License
+This module is licensed under the MIT License.
+
+```python
+from dsg_lib.common_functions import calendar_functions
+
+month_list: list = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
+month_names: list = [
+    "january",
+    "february",
+    "march",
+    "april",
+    "may",
+    "june",
+    "july",
+    "august",
+    "september",
+    "october",
+    "november",
+    "december",
+    "bob",
+]
+
+
+def calendar_check_number():
+    for i in month_list:
+        month = calendar_functions.get_month(month=i)
+        print(month)
+
+
+def calendar_check_name():
+    for i in month_names:
+        month = calendar_functions.get_month_number(month_name=i)
+        print(month)
+
+
+if __name__ == "__main__":
+    calendar_check_number()
+    calendar_check_name()
+```

docs/examples/csv_example.md

@@ -0,0 +1,117 @@
+# csv_example Example
+
+# CSV Example Module
+
+This module provides examples of how to work with CSV files using the `dsg_lib` library. It includes functions for saving data to a CSV file, opening and reading data from a CSV file, and creating sample files for testing purposes. The module is designed to demonstrate the usage of the `file_functions` and `logging_config` utilities provided by `dsg_lib`.
+
+## Functions
+
+### `save_some_data(example_list: list)`
+Saves a list of data to a CSV file. The function uses the `save_csv` utility from `dsg_lib` to write the data to a file. The file is saved with a specified delimiter and quote character.
+
+- **Parameters**:
+  - `example_list` (list): A list of lists containing the data to be saved.
+- **Notes**:
+  - The file is saved in the `/data` directory with the name `your-file-name.csv`.
+  - The delimiter used is `|`, and the quote character is `"`.
+  - Refer to the `save_csv` documentation for additional options.
+
+### `open_some_data(the_file_name: str) -> dict`
+Opens a CSV file and returns its contents as a dictionary. This function assumes the CSV file has a header row and uses the `open_csv` utility from `dsg_lib`.
+
+- **Parameters**:
+  - `the_file_name` (str): The name of the CSV file to open.
+- **Returns**:
+  - `dict`: A dictionary representation of the CSV file's contents.
+- **Notes**:
+  - Additional options such as delimiter, quote level, and space handling can be configured.
+  - Refer to the Python CSV documentation for more details: [Python CSV Documentation](https://docs.python.org/3/library/csv.html).
+
+### `sample_files()`
+Creates sample files for testing purposes. This function uses the `create_sample_files` utility from `dsg_lib`.
+
+- **Notes**:
+  - The sample file is named `test_sample` and contains 1000 rows of data.
+
+## Example Usage
+
+```python
+if __name__ == "__main__":
+    # Save example data to a CSV file
+    save_some_data(example_list)
+
+    # Open and read data from a CSV file
+    opened_file = open_some_data("your-file-name.csv")
+    print(opened_file)
+
+    # Create sample files for testing
+    sample_files()
+```
+
+## Logging
+
+The module configures logging using the `config_log` utility from `dsg_lib`. The logging level is set to `DEBUG` to provide detailed information during execution.
+
+## License
+This module is licensed under the MIT License.
+
+```python
+from dsg_lib.common_functions.file_functions import (
+    create_sample_files,
+    open_csv,
+    save_csv,
+)
+from dsg_lib.common_functions.logging_config import config_log
+
+config_log(logging_level="DEBUG")
+
+example_list = [
+    ["thing_one", "thing_two"],
+    ["a", "b"],
+    ["c", "d"],
+    ["e", "f"],
+    ["g", "h"],
+]
+
+
+def save_some_data(example_list: list):
+    # function requires file_name and data list to be sent.
+    # see documentation for additonal information
+    save_csv(
+        file_name="your-file-name.csv",
+        data=example_list,
+        root_folder="/data",
+        delimiter="|",
+        quotechar='"',
+    )
+
+
+def open_some_data(the_file_name: str) -> dict:
+    """
+    function requires file_name and a dictionary will be returned
+    this function is designed with the idea that the CSV file has a header row.
+    see documentation for additonal information
+    options
+        file_name: str | "myfile.csv"
+        delimit: str | example - ":" single character only inside quotes
+        quote_level:str | ["none","non-numeric","minimal","all"] default is minimal
+        skip_initial_space:bool | default is True
+    See Python documentation as needed https://docs.python.org/3/library/csv.html
+    """
+
+    result: dict = open_csv(file_name=the_file_name)
+    return result
+
+
+def sample_files():
+    filename = "test_sample"
+    samplesize = 1000
+    create_sample_files(filename, samplesize)
+
+
+if __name__ == "__main__":
+    # save_some_data(example_list)
+    # opened_file: dict = open_some_data("your-file-name.csv")
+    # print(opened_file)
+    sample_files()
+```