Merge pull request #18 from ambitus/dev

Release 1.0a2

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+    ignore = W503,E122,E203
+    max-line-length = 99
+    per-file-ignores = __init__.py:F401
+    exclude = venv_*

.github/workflows/.github-actions.yml

@@ -0,0 +1,24 @@
+name: pyRACF Linting & Unit Test
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Python Setup
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+    - name: Install Dependencies
+      run: |
+        python3 -m pip install --upgrade pip
+        python3 -m pip install -r requirements.txt
+        python3 -m pip install -r requirements-development.txt
+    - name: Flake8
+      run: flake8 .
+    - name: Pylint
+      run: pylint --recursive=y .
+    - name: Unit Test
+      run: coverage run tests/test_runner.py
+    - name: Code Coverage
+      run: coverage report -m

.pre-commit-config.yaml

@@ -43,4 +43,4 @@ repos:
         language: system
         pass_filenames: false
         always_run: true
-        verbose: true
+        verbose: true

CONTRIBUTING.md

@@ -86,7 +86,7 @@ If you fix a bug, open a GitHub pull request against the `dev` branch with the f
 
 ### Adding or Fixing Documentation
 
-If you want to improve the current documentation, that includes adding new documentation, fixing grammar, spelling, and format errors open a GitHub pull request against the `gh-pages` branch with your changes.
+If any updates need to be made to the pyRACF documentation, open a GitHub pull request against the `gh-pages-dev` branch with your changes. This may include updates to document new functionality or updates to correct errors or mistakes in the existing documentation.
 
 ## Style Guidelines
 
@@ -100,9 +100,9 @@ If you want to improve the current documentation, that includes adding new docum
 
 When contributing to pyRACF, think about the following:
 
-* Make any necessary updates to `setup.py`.
+* Make any necessary updates to `pyproject.toml`.
 * Make any necessary updates to `README.md`.
-* Make any necessary updates to the gitHub pages documentation in the `gh-pages` branch.
+* Make any necessary updates to the gitHub pages documentation in the `gh-pages` branch _(Pull requests should be opened against the `gh-pages-dev` branch)_.
 * Add any available test cases to `/tests`.
 * Verify `__init__.py` files are updated properly.
 * Ensure that you have __pre-commit Hooks__ setup to ensure that **isort**, **black**, **flake8**, and **pylint** are run against the code for every commit you make.

Jenkinsfile

@@ -1,52 +1,296 @@
+def python_versions
+def python_executables_and_wheels_map
+
 pipeline {
     agent {
         node {
             label 'zOS_pyRACF'
         }
     }
 
+    parameters {
+        // Note: Each Python version listed must be installed on the 
+        // build agent and must be added to '$PATH' and '$LIBPATH'.
+        string (
+            name: "pythonVersions",
+            defaultValue: "",
+            description: "(Required Always) Comma separated list of Python versions to build wheels for (i.e., Use '10,11' for Python 3.10 and Python 3.11)."
+        )
+        booleanParam(
+            name: "createRelease",
+            defaultValue: false,
+            description: "Toggle whether or not to create a release from this revision."
+        )
+        string(
+            name: "releaseTag",
+            defaultValue: "",
+            description: "(Required When Creating Releases) This will be the git tag and version number of the release."
+        )
+        string(
+            name: "gitHubMilestoneLink",
+            defaultValue: "",
+            description: "(Required When Creating Releases) This is the GitHub Milestore URL that coresponds to the release."
+        )
+        booleanParam(
+            name: "preRelease",
+            defaultValue: true,
+            description: "Toggle whether or not this is a pre-release."
+        )
+    }
+
     options {
         ansiColor('css')
     }
 
     stages {
-        stage('Install Dependencies') {
+        stage('Parameter Validation') {
+            steps {
+                script {
+                    if (params.pythonVersions == "") {
+                        error("'pythonVersions' is required parameter.")
+                    }
+                    if (params.createRelease) {
+                        if (params.releaseTag == "") {
+                            error("'releaseTag' is a required parameter when creating a release.")
+                        }
+                        if (params.gitHubMilestoneLink == "") {
+                            error("'gitHubMilestoneLink' is a required parameter when creating a release.")
+                        }
+                    }
+                }
+            }
+        }
+        stage('Build Python Executables & Wheels Map') {
             steps {
-                // Uninstall pyRACF to clean environment.
-                // Install wheel to build and publish pyRACF as a python wheel.
-                sh """
-                    python3 --version
-                    python3 -m pip uninstall pyracf -y
-                    python3 -m pip install -r requirements.txt
-                    python3 -m pip install -r requirements-development.txt
-                    python3 -m pip install wheel>=0.41.0
-                """
+                script {
+                    python_versions = params.pythonVersions.split(",")
+                    python_executables_and_wheels_map = (
+                        create_python_executables_and_wheels_map(python_versions)
+                    )
+                }
             }
         }
-        stage('Unit Test') {
+        stage('Build Virtual Environments') {
             steps {
-                sh """
-                    flake8 .
-                    pylint --recursive=y .
-                    coverage run tests/test_runner.py
-                    coverage report -m
-                """
+                script {
+                    for (python in python_executables_and_wheels_map.keySet()) {
+                        build_virtual_environment(python)
+                    }
+                }
+            }
+        }
+        stage('Lint & Unit Test') {
+            steps {
+                script {
+                    for (python in python_executables_and_wheels_map.keySet()) {
+                        lint_and_unit_test(python)
+                    }
+                }
             }
         }
         stage('Function Test') {
             steps {
-                sh """
-                    python3 setup.py install --user
-                    cd tests/function_test
-                    python3 function_test.py
-                """
+                script {
+                    for (python in python_executables_and_wheels_map.keySet()) {
+                        function_test(
+                            python, 
+                            python_executables_and_wheels_map[python]["defaultName"]
+                        )
+                    }
+                }
             }
         }
         stage('Publish') {
-            when { tag "*" }
+            when { 
+                expression { params.createRelease == true }    
+            }
             steps {
-                sh "python3 setup.py bdist_wheel upload -r test"
+                publish(
+                    python_executables_and_wheels_map,
+                    params.releaseTag, 
+                    env.BRANCH_NAME, 
+                    params.gitHubMilestoneLink,
+                    params.preRelease
+                )
             }
         }
     }
+    post {
+        always {
+            echo "Cleaning up workspace..."
+            cleanWs()
+        }
+    }
+}
+
+def create_python_executables_and_wheels_map(python_versions) {
+    def os = sh(
+        returnStdout: true, 
+        script: "uname"
+    ).trim().replace("/", "").toLowerCase()
+    def zos_release = sh(
+        returnStdout: true, 
+        script: "uname -r"
+    ).trim().replace(".", "_")
+    def processor = sh(
+        returnStdout: true, 
+        script: "uname -m"
+    ).trim()
+    def pyracf_version = sh(
+        returnStdout: true, 
+        script: "cat pyproject.toml | grep version | cut -d'=' -f2 | cut -d'\"' -f2"
+    ).trim()
+
+    python_executables_and_wheels_map = [:]
+
+    for (version in python_versions) {
+        python_executables_and_wheels_map["python3.${version}"] = [
+            "defaultName": (
+                "pyracf-${pyracf_version}-cp3${version}-cp3${version}-${os}_${zos_release}_${processor}.whl"
+            ),
+            "publishName": "pyracf-${pyracf_version}-cp3${version}-none-any.whl"
+        ]
+    }
+
+    return python_executables_and_wheels_map
+}
+
+def build_virtual_environment(python) {
+    echo "Building virtual environment for '${python}'..."
+
+    sh """
+        ${python} --version
+        rm -rf venv_${python}
+        ${python} -m venv venv_${python}
+        . venv_${python}/bin/activate
+        ${python} -m pip install -r requirements.txt
+        ${python} -m pip install -r requirements-development.txt
+    """
+}
+
+def lint_and_unit_test(python) {
+    echo "Running linters and unit tests for '${python}'..."
+
+    sh """
+        . venv_${python}/bin/activate
+        ${python} -m flake8 .
+        ${python} -m pylint --recursive=y .
+        cd tests
+        ${python} -m coverage run test_runner.py
+        ${python} -m coverage report -m
+    """
+}
+
+def function_test(python, wheel) {
+    echo "Running function test for '${python}'..."
+
+    sh """
+        git clean -f -d -e 'venv_*'
+        . venv_${python}/bin/activate
+        ${python} -m pip wheel .
+        ${python} -m pip install ${wheel}
+        cd tests/function_test
+        ${python} function_test.py
+    """
+}
+
+def publish(
+        python_executables_and_wheels_map, 
+        release, 
+        git_branch, 
+        milestone, 
+        pre_release
+) {
+    if (pre_release == true) {
+        pre_release = "true"
+    }
+    else {
+        pre_release = "false"
+    }
+    withCredentials(
+        [
+            string(
+                credentialsId: 'pyracf-github-access-token',
+                variable: 'github_access_token'
+            )
+        ]
+    ) {
+
+        // Creating GitHub releases: 
+        // https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release
+        // Uploading release assets: 
+        // https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28#upload-a-release-asset
+
+        // Use single quotes for credentials since it is the most secure
+        // method for interpolating secrets according to the Jenkins docs:
+        // https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#string-interpolation
+
+        echo "Creating '${release}' GitHub release..."
+
+        def description = build_description(python_executables_and_wheels_map, release, milestone)
+
+        def release_id = sh(
+            returnStdout: true,
+            script: (
+                'curl -f -v -L '
+                + '-X POST '
+                + '-H "Accept: application/vnd.github+json" '
+                + '-H "Authorization: Bearer ${github_access_token}" '
+                + '-H "X-GitHub-Api-Version: 2022-11-28" '
+                + "https://api.github.com/repos/ambitus/pyracf/releases "
+                + "-d '{"
+                + "     \"tag_name\": \"${release}\","
+                + "     \"target_commitish\": \"${git_branch}\","
+                + "     \"name\": \"${release}\","
+                + "     \"body\": \"${description}\","
+                + "     \"draft\": false,"
+                + "     \"prerelease\": ${pre_release},"
+                + "     \"generate_release_notes\":false"
+                + "}' | grep '\"id\": ' | head -n1 | cut -d':' -f2 | cut -d',' -f1"
+            )
+        ).trim()
+
+        for (python in python_executables_and_wheels_map.keySet()) {
+            def wheel_default = python_executables_and_wheels_map[python]["defaultName"]
+            def wheel_publish = python_executables_and_wheels_map[python]["publishName"]
+
+            echo "Cleaning repo and building '${wheel_default}'..."
+
+            sh """
+                git clean -f -d -e 'venv_*'
+                . venv_${python}/bin/activate
+                ${python} -m pip wheel .
+            """
+
+            echo "Uploading '${wheel_default}' as '${wheel_publish}' to '${release}' GitHub release..."
+
+            sh(
+                'curl -f -v -L '
+                + '-X POST '
+                + '-H "Accept: application/vnd.github+json" '
+                + '-H "Authorization: Bearer ${github_access_token}" '
+                + '-H "X-GitHub-Api-Version: 2022-11-28" '
+                + '-H "Content-Type: application/octet-stream" '
+                + "\"https://uploads.github.com/repos/ambitus/pyracf/releases/${release_id}/assets?name=${wheel_publish}\" "
+                + "--data-binary \"@${wheel_default}\""
+            )
+        }
+    }
+}
+
+def build_description(python_executables_and_wheels_map, release, milestone) {
+    def description = "Release Milestone: ${milestone}\\n \\n \\n"
+
+    for (python in python_executables_and_wheels_map.keySet()) {
+        def wheel = python_executables_and_wheels_map[python]["publishName"]
+        def python_executable = python
+        def python_label = python.replace("python", "Python ")
+        description += (
+            "Install for ${python_label}:\\n"
+            + "```\\ncurl -O -L https://github.com/ambitus/pyracf/releases/download/${release}/${wheel} "
+            + "&& ${python_executable} -m pip install ${wheel}\\n```\\n"
+        )
+    }
+
+    return description
 }