edq-utils 0.0.8__tar.gz → 0.1.1__tar.gz

{edq_utils-0.0.8 → edq_utils-0.1.1}/.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.0.8 → edq_utils-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.0.8
+Version: 0.1.1
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License
@@ -35,6 +35,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: json5>=0.9.14
+Requires-Dist: platformdirs
 Requires-Dist: requests
 Requires-Dist: requests-toolbelt
 Provides-Extra: dev
@@ -49,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.0.8 → edq_utils-0.1.1}/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.0.8 → edq_utils-0.1.1}/edq/__init__.py

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

{edq_utils-0.0.8 → edq_utils-0.1.1}/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.0.8 → edq_utils-0.1.1}/edq_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.0.8
+Version: 0.1.1
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License
@@ -35,6 +35,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: json5>=0.9.14
+Requires-Dist: platformdirs
 Requires-Dist: requests
 Requires-Dist: requests-toolbelt
 Provides-Extra: dev
@@ -49,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.0.8 → edq_utils-0.1.1}/edq_utils.egg-info/SOURCES.txt

@@ -85,10 +85,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.0.8 → edq_utils-0.1.1}/edq_utils.egg-info/requires.txt

@@ -1,4 +1,5 @@
 json5>=0.9.14
+platformdirs
 requests
 requests-toolbelt
 

{edq_utils-0.0.8 → edq_utils-0.1.1}/requirements.txt

@@ -1,3 +1,4 @@
 json5>=0.9.14
+platformdirs
 requests
 requests-toolbelt

edq_utils-0.1.1/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.0.8 → edq_utils-0.1.1}/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.1/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.1/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>