edq-utils 0.1.0__tar.gz → 0.1.2__tar.gz

{edq_utils-0.1.0 → edq_utils-0.1.2}/.github/workflows/main.yml

@@ -51,13 +51,80 @@ jobs:
         shell: bash
         run: ./scripts/run_tests.sh
 
-  deploy:
+  docs:
     needs: test
+    if: ${{ github.event_name == 'push' && github.repository_owner == 'edulinq' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) }}
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    strategy:
+      matrix:
+        python-version: ['3.11']
+        os: ['ubuntu-24.04']
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache Python Dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-os:${{ matrix.os }}-python:${{ matrix.python-version }}-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements-dev.txt') }}
+
+      - name: Install Dependencies
+        shell: bash
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build Site
+        shell: bash
+        run: |
+            git checkout main
+            ./scripts/build_site.sh
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'build/site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  deploy:
+    # Run after test and docs, but allow docs to have been skipped (since we will only test deploy then).
+    needs: [test, docs]
+    if: |
+        (always() && !cancelled())
+        && (
+            (needs.test.result == 'success')
+            && ((needs.docs.result == 'success') || (needs.docs.result == 'skipped'))
+        )
 
     strategy:
       matrix:
         python-version: ['3.11']
-        os: ['ubuntu-22.04']
+        os: ['ubuntu-24.04']
 
     runs-on: ${{ matrix.os }}
 

{edq_utils-0.1.0 → edq_utils-0.1.2}/.pylintrc

@@ -104,10 +104,6 @@ recursive=no
 # source root.
 source-roots=
 
-# When enabled, pylint would attempt to guess common misconfiguration and emit
-# user-friendly hints instead of false-positive error messages.
-suggestion-mode=yes
-
 # Allow loading of arbitrary C extensions. Extensions are imported into the
 # active Python interpreter and may run arbitrary code.
 unsafe-load-any-extension=no

{edq_utils-0.1.0 → edq_utils-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.1.0
+Version: 0.1.2
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License
@@ -50,6 +50,12 @@ Dynamic: license-file
 
 Common utilities used by EduLinq Python projects.
 
+Links:
+ - [API Reference](https://edulinq.github.io/python-utils)
+ - [Installation / Requirements](#installation--requirements)
+ - [Configuration System](#configuration-system)
+   - [Configuration Sources](#configuration-sources)
+
 ## Installation / Requirements
 
 This project requires [Python](https://www.python.org/) >= 3.8.

{edq_utils-0.1.0 → edq_utils-0.1.2}/README.md

@@ -2,6 +2,12 @@
 
 Common utilities used by EduLinq Python projects.
 
+Links:
+ - [API Reference](https://edulinq.github.io/python-utils)
+ - [Installation / Requirements](#installation--requirements)
+ - [Configuration System](#configuration-system)
+   - [Configuration Sources](#configuration-sources)
+
 ## Installation / Requirements
 
 This project requires [Python](https://www.python.org/) >= 3.8.

{edq_utils-0.1.0 → edq_utils-0.1.2}/edq/__init__.py

@@ -2,4 +2,4 @@
 General Python tools used by several EduLinq projects.
 """
 
-__version__ = '0.1.0'
+__version__ = '0.1.2'

{edq_utils-0.1.0 → edq_utils-0.1.2}/edq/testing/cli.py

@@ -35,6 +35,7 @@ import edq.util.json
 import edq.util.pyimport
 
 TEST_CASE_SEP: str = '---'
+OUTPUT_SEP: str = '+++'
 DATA_DIR_ID: str = '__DATA_DIR__'
 ABS_DATA_DIR_ID: str = '__ABS_DATA_DIR__'
 TEMP_DIR_ID: str = '__TEMP_DIR__'
@@ -149,7 +150,7 @@ class CLITestInfo:
         """
         Split stdout and stderr into different strings for testing.
         By default, these two will be combined.
-        If both are non-empty, then they will be joined like: f"{stdout}\n{TEST_CASE_SEP}\n{stderr}".
+        If both are non-empty, then they will be joined like: f"{stdout}\n{OUTPUT_SEP}\n{stderr}".
         Otherwise, only the non-empty one will be present with no separator.
         Any stdout assertions will be applied to the combined text.
         """
@@ -293,7 +294,7 @@ def _get_test_method(test_name: str, path: str, data_dir: str) -> typing.Callabl
 
         if (not test_info.split_stdout_stderr):
             if ((len(stdout_text) > 0) and (len(stderr_text) > 0)):
-                stdout_text = f"{stdout_text}\n{TEST_CASE_SEP}\n{stderr_text}"
+                stdout_text = f"{stdout_text}\n{OUTPUT_SEP}\n{stderr_text}"
             elif (len(stderr_text) > 0):
                 stdout_text = stderr_text
 

edq_utils-0.1.2/edq/testing/testdata/cli/tests/help_base.txt

@@ -0,0 +1,9 @@
+{
+    "cli": "edq.cli.version",
+    "arguments": [
+        '--help'
+    ],
+    "error": true
+}
+---
+builtins.SystemExit: 0

{edq_utils-0.1.0 → edq_utils-0.1.2}/edq/testing/unittest.py

@@ -14,6 +14,20 @@ class BaseTest(unittest.TestCase):
     maxDiff = None
     """ Don't limit the size of diffs. """
 
+    def assertJSONEqual(self, a: typing.Any, b: typing.Any, message: typing.Union[str, None] = None) -> None:  # pylint: disable=invalid-name
+        """
+        Like unittest.TestCase.assertEqual(),
+        but uses a default assertion message containing the full JSON representation of the arguments.
+        """
+
+        a_json = edq.util.json.dumps(a, indent = 4)
+        b_json = edq.util.json.dumps(b, indent = 4)
+
+        if (message is None):
+            message = FORMAT_STR % (a_json, b_json)
+
+        super().assertEqual(a, b, msg = message)
+
     def assertJSONDictEqual(self, a: typing.Any, b: typing.Any, message: typing.Union[str, None] = None) -> None:  # pylint: disable=invalid-name
         """
         Like unittest.TestCase.assertDictEqual(),

{edq_utils-0.1.0 → edq_utils-0.1.2}/edq/util/net.py

@@ -666,6 +666,7 @@ def make_request(method: str, url: str,
         params_to_skip: typing.Union[typing.List[str], None] = None,
         http_exchange_extension: str = DEFAULT_HTTP_EXCHANGE_EXTENSION,
         add_http_prefix: bool = True,
+        additional_requests_options: typing.Union[typing.Dict[str, typing.Any], None] = None,
         **kwargs: typing.Any) -> typing.Tuple[requests.Response, str]:
     """
     Make an HTTP request and return the response object and text body.
@@ -686,6 +687,9 @@ def make_request(method: str, url: str,
     if (files is None):
         files = []
 
+    if (additional_requests_options is None):
+        additional_requests_options = {}
+
     # Add in the anchor as a header (since it is not traditionally sent in an HTTP request).
     if (send_anchor_header):
         headers = headers.copy()
@@ -693,11 +697,12 @@ def make_request(method: str, url: str,
         parts = urllib.parse.urlparse(url)
         headers[ANCHOR_HEADER_KEY] = parts.fragment.lstrip('#')
 
-    options = {
+    options = additional_requests_options.copy()
+    options.update({
         'headers': headers,
         'files': files,
         'timeout': timeout_secs,
-    }
+    })
 
     if (method == 'GET'):
         options['params'] = data

{edq_utils-0.1.0 → edq_utils-0.1.2}/edq_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.1.0
+Version: 0.1.2
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License
@@ -50,6 +50,12 @@ Dynamic: license-file
 
 Common utilities used by EduLinq Python projects.
 
+Links:
+ - [API Reference](https://edulinq.github.io/python-utils)
+ - [Installation / Requirements](#installation--requirements)
+ - [Configuration System](#configuration-system)
+   - [Configuration Sources](#configuration-sources)
+
 ## Installation / Requirements
 
 This project requires [Python](https://www.python.org/) >= 3.8.

{edq_utils-0.1.0 → edq_utils-0.1.2}/edq_utils.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ edq/testing/testdata/cli/data/configs/empty/edq-config.json
 edq/testing/testdata/cli/data/configs/simple-1/edq-config.json
 edq/testing/testdata/cli/data/configs/simple-2/edq-config.json
 edq/testing/testdata/cli/data/configs/value-number/edq-config.json
+edq/testing/testdata/cli/tests/help_base.txt
 edq/testing/testdata/cli/tests/platform_skip.txt
 edq/testing/testdata/cli/tests/version_base.txt
 edq/testing/testdata/cli/tests/config/list/config_list_base.txt
@@ -85,10 +86,15 @@ edq_utils.egg-info/SOURCES.txt
 edq_utils.egg-info/dependency_links.txt
 edq_utils.egg-info/requires.txt
 edq_utils.egg-info/top_level.txt
+scripts/build_site.sh
 scripts/check_all.sh
 scripts/check_lint.sh
 scripts/check_python_version.sh
 scripts/check_strict_types.sh
 scripts/check_types.sh
 scripts/gen_docs.sh
-scripts/run_tests.sh
+scripts/run_tests.sh
+scripts/template/html/favicon.ico
+scripts/template/html/index.html
+scripts/template/html/css/style.css
+scripts/template/html/images/favicon.png

edq_utils-0.1.2/scripts/build_site.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+
+# Create a full website including all documentation ready to be deployed.
+# This script should only be done from a clean repo on the main branch.
+# Documentation will be generated from the main branch (latest) as well as each version tag.
+
+readonly THIS_DIR="$(cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd | xargs realpath)"
+readonly ROOT_DIR="${THIS_DIR}/.."
+readonly TEMPLATE_HTML_DIR="${THIS_DIR}/template/html"
+readonly BUILD_DIR="${ROOT_DIR}/build"
+readonly DOCS_BUILD_DIR="${BUILD_DIR}/html"
+readonly SITE_BUILD_DIR="${BUILD_DIR}/site"
+readonly DOCS_DIRNAME='docs'
+readonly DOCS_OUT_DIR="${SITE_BUILD_DIR}/${DOCS_DIRNAME}"
+readonly GEN_DOCS_SCRIPT="${THIS_DIR}/gen_docs.sh"
+
+readonly MAIN_BRANCH="main"
+
+readonly REPO='edulinq/python-utils'
+readonly REPO_DISPLAY_NAME='EduLinq Python Utils'
+readonly REPO_MAIN_PACKAGE_NAME='edq'
+
+readonly INDEX_TITLE_LOCATION='<header class="pdoc">'
+readonly MODULE_TITLE_LOCATION='<section class="module-info">'
+
+readonly API_DOC_MARKER='<!-- API-DOC-MARKER -->'
+
+# Don't generate any docs for this version or earlier.
+# Because of this specific tag, we can just do a lexicographic comparison.
+readonly ONLY_AFTER_TAG='v0.1.0'
+
+function check_git() {
+    if [ ! -z "$(git status --porcelain)" ] ; then
+        echo "ERROR: Repository is not clean."
+        exit 1
+    fi
+
+    if [ $(git branch --show-current) != 'main' ] ; then
+        echo "ERROR: Repository is not on the main branch."
+        exit 2
+    fi
+
+    return 0
+}
+
+function gen_docs() {
+    local label=$1
+    local reference=$2
+    local dirname=$3
+
+    echo "Generating docs for '${label}'."
+
+    rm -rf "${DOCS_BUILD_DIR}"
+    ${GEN_DOCS_SCRIPT} "${DOCS_BUILD_DIR}"
+
+    # Add in the label to the landing pages.
+    local git_link="https://github.com/${REPO}/tree/${reference}"
+
+    local index_title="<h1 style='flex-grow: 1'>${REPO_DISPLAY_NAME} API Reference: <a href='${git_link}'>${label}</a></h1>"
+    sed -i "s#${INDEX_TITLE_LOCATION}#${INDEX_TITLE_LOCATION}${index_title}#" "${DOCS_BUILD_DIR}/index.html"
+
+    local module_title="<h1>${REPO_DISPLAY_NAME} API Reference: <a href='${git_link}'>${label}</a></h1>"
+    sed -i "s#${MODULE_TITLE_LOCATION}#${MODULE_TITLE_LOCATION}${module_title}#" "${DOCS_BUILD_DIR}/${REPO_MAIN_PACKAGE_NAME}.html"
+
+    # Moved the compiled documentation to the main site.
+    mkdir -p "${DOCS_OUT_DIR}"
+    mv "${DOCS_BUILD_DIR}" "${DOCS_OUT_DIR}/${dirname}"
+
+    # Add this documentation to the main index page.
+    local index_li="<li><a href='${DOCS_DIRNAME}/${dirname}/index.html'>${label}</a></li>"
+    sed -i "s#${API_DOC_MARKER}#${index_li}${API_DOC_MARKER}#" "${SITE_BUILD_DIR}/index.html"
+}
+
+function main() {
+    if [[ $# -ne 0 ]]; then
+        echo "USAGE: $0"
+        exit 1
+    fi
+
+    set -e
+    trap exit SIGINT
+
+    cd "${ROOT_DIR}"
+
+    # Remove any existing output.
+    rm -rf "${SITE_BUILD_DIR}"
+    mkdir -p "${SITE_BUILD_DIR}"
+    cp -r "${TEMPLATE_HTML_DIR}"/* "${SITE_BUILD_DIR}"/
+
+    # Ensure that the repo looks good.
+    check_git
+
+    # Generate the latest documentation.
+    local git_hash=$(git rev-parse --short HEAD)
+    gen_docs "latest (${git_hash})" "${git_hash}" 'latest'
+
+    # Generate docs for each tagged version.
+    for tag in $(git tag -l | grep -P '^v\d+\.\d+\.\d+' | sort -r --version-sort) ; do
+        if [[ ! "${tag}" > "${ONLY_AFTER_TAG}" ]] ; then
+            continue
+        fi
+
+        git checkout --quiet "${tag}"
+        gen_docs "${tag}" "${tag}" "${tag}"
+    done
+
+    # Move back to main.
+    git checkout --quiet main
+
+    return 0
+}
+
+[[ "${BASH_SOURCE[0]}" == "${0}" ]] && main "$@"

{edq_utils-0.1.0 → edq_utils-0.1.2}/scripts/gen_docs.sh

@@ -14,7 +14,7 @@ function main() {
     set -e
     trap exit SIGINT
 
-    local outputDir="${ROOT_DIR}/html"
+    local outputDir="${ROOT_DIR}/build/html"
     if [[ $# -gt 0 ]]; then
         outputDir=$1
     fi

edq_utils-0.1.2/scripts/template/html/css/style.css

@@ -0,0 +1,20 @@
+ul {
+    margin: 0;
+}
+
+h1, p {
+    margin: 0;
+}
+
+.page {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    flex-wrap: nowrap;
+    justify-content: flex-start;
+    align-items: center;
+    gap: 2em;
+}
+
+

edq_utils-0.1.2/scripts/template/html/index.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset='utf-8'/>
+        <meta name='viewport' content='width=device-width, initial-scale=1.0'>
+
+        <title>EduLinq Python Utils</title>
+
+        <link rel="icon" href="images/favicon.png">
+
+        <link rel='stylesheet' type='text/css' href='css/style.css'>
+    </head>
+    <body>
+        <div class='page'>
+            <h1>EduLinq Python Utils</h1>
+
+            <div class='overview'>
+                <p>Common Python utilities used by EduLinq.</p>
+                <p>You can find the main repository at <a href='https://github.com/edulinq/python-utils'>github.com/edulinq/python-utils</a>.</p>
+                <p>Below you can find API references for various different version.</p>
+                </p>
+            </div>
+
+            <div class='docs'>
+                <span>Versions:</span>
+                <ul>
+                    <!-- API-DOC-MARKER -->
+                </ul>
+            </div>
+        </div>
+    </body>
+</html>