Merge branch 'master' into create_credential_by_id

.github/workflows/python-package.yml

@@ -0,0 +1,81 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: CI_TEST
+
+on:
+  push:
+    paths:
+      - '**.py'
+      - '**.yml'
+  pull_request:
+    branches: [ "master" ]
+  workflow_dispatch: # allow manual run
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        token: ["stable"]
+
+    steps:
+    - name: Harden Runner
+      uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
+      with:
+        egress-policy: audit
+        allowed-endpoints: >
+          azure.archive.ubuntu.com:80
+          esm.ubuntu.com:443
+          files.pythonhosted.org:443
+          ftp-chi.osuosl.org:443
+          ftp-nyc.osuosl.org:443
+          get.jenkins.io:443
+          github.com:443
+          api.github.com:443
+          int.api.stepsecurity.io:443
+          mirror.xmission.com:443
+          motd.ubuntu.com:443
+          packages.microsoft.com:443
+          ppa.launchpadcontent.net:443
+          pypi.org:443
+          updates.jenkins-ci.org:80
+          updates.jenkins.io:443
+          mirrors.updates.jenkins.io:443
+          updates.jenkins.io:80
+
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+
+    - name: Install python
+      run: uv python install
+
+    - name: setup java 17
+      uses: actions/setup-java@v3
+      with:
+        java-version: '17'
+        distribution: 'temurin'
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get install libkrb5-dev
+
+    - name: Lint with flake8
+      run: |
+        uv run flake8 jenkinsapi/ --count --select=E9,F63,F7,F82 --ignore F821,W503,W504 --show-source --statistics
+        uv run flake8 jenkinsapi/ --count --exit-zero --max-complexity=10 --max-line-length=79 --statistics
+
+    - name: Test with pytest
+      env:
+        JENKINS_VERSION: ${{ matrix.token }}
+      run: |
+        uv run pytest -sv --cov=jenkinsapi --cov-report=term-missing --cov-report=xml jenkinsapi_tests

.gitignore

@@ -29,3 +29,5 @@ coverage.xml
 .vscode/
 *.war
 venv/
+tags
+.pytype/

.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+---
+repos:
+  - repo: https://github.com/psf/black
+    rev: 22.10.0
+    hooks:
+      - id: black
+        args:
+          - --line-length=79
+          # these folders wont be formatted by black
+          - --exclude="""\.git |
+            \.__pycache__|
+            \.hg|
+            \.mypy_cache|
+            \.tox|
+            \.venv|
+            _build|
+            buck-out|
+            build|
+            dist"""
+        language_version: python3
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+      - id: check-byte-order-marker
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-vcs-permalinks
+      - id: debug-statements
+      - id: check-yaml
+        files: .*\.(yaml|yml)$

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 PyContribs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -1,7 +1,7 @@
 .PHONY: test lint tox coverage dist
 
 test:
-	py.test -sv jenkinsapi_tests
+	pytest -sv jenkinsapi_tests
 
 lint:
 	pycodestyle
@@ -14,4 +14,4 @@ dist:
 	python setup.py sdist bdist_wheel
 
 coverage:
-	py.test -sv --cov=jenkinsapi --cov-report=term-missing --cov-report=xml jenkinsapi_tests
+	pytest -sv --cov=jenkinsapi --cov-report=term-missing --cov-report=xml jenkinsapi_tests

README.rst

@@ -4,75 +4,48 @@ jenkinsapi
 .. image:: https://badge.fury.io/py/jenkinsapi.png
     :target: http://badge.fury.io/py/jenkinsapi
 
-.. image:: https://travis-ci.com/pycontribs/jenkinsapi.png?branch=master
-        :target: https://travis-ci.com/pycontribs/jenkinsapi
-
 .. image:: https://codecov.io/gh/pycontribs/jenkinsapi/branch/master/graph/badge.svg
         :target: https://codecov.io/gh/pycontribs/jenkinsapi
 
-.. image:: https://requires.io/github/pycontribs/jenkinsapi/requirements.png?branch=master
-        :target: https://requires.io/github/pycontribs/jenkinsapi/requirements/?branch=master
-        :alt: Requirements Status
-
 About this library
 -------------------
 
 Jenkins is the market leading continuous integration system, originally created by Kohsuke Kawaguchi.
 
-Jenkins (and It's predecessor Hudson) are useful projects for automating common development tasks (e.g. unit-testing, production batches) - but they are somewhat Java-centric. Thankfully the designers have provided an excellent and complete REST interface. This library wraps up that interface as more conventional python objects in order to make many Jenkins oriented tasks easier to automate.
+Jenkins (and its predecessor Hudson) are useful projects for automating common development tasks (e.g. unit-testing, production batches) - but they are somewhat Java-centric.
+| Jenkinsapi makes scripting Jenkins tasks a breeze by wrapping the REST api into familiar python objects.
+| Here is a list of some of the most commonly used functionality
 
-This library allows you to automate most common Jenkins operations using Python, such as:
-
-* Ability to add/remove/query Jenkins jobs
-* Ability to execute jobs and:
+* Add, remove, and query Jenkins jobs
+* Control pipeline execution
     * Query the results of a completed build
     * Block until jobs are complete or run jobs asyncronously
     * Get objects representing the latest builds of a job
-* Work with build artifacts:
+* Artifact management
     * Search for artifacts by simple criteria
     * Install artifacts to custom-specified directory structures
-* Ability to search for builds by source code revision
-* Ability to add/remove/query:
-    * Slaves (Webstart and SSH slaves)
+* Search for builds by source code revision
+* Create, destroy, and monitor
+    * Build nodes (Webstart and SSH slaves)
     * Views (including nested views using NestedViews Jenkins plugin)
     * Credentials (username/password and ssh key)
-* Username/password auth support for jenkins instances with auth turned on
-* Ability to script jenkins installation including plugins
-
-For a full documentation spec of what this library supports see: http://jenkinsapi.readthedocs.io/en/latest/index.html
+* Authentication support for username and password
+* Manage jenkins and plugin installation
 
-Python versions
----------------
-
-The project has been tested against Python versions:
+Full library capabilities are outlined in the `Documentation <http://jenkinsapi.readthedocs.io/en/latest/index.html>`_
 
-* 2.7
-* 3.4
-* 3.5
-* 3.6
-* 3.7
-
-Jenkins versions
-----------------
-
-Project tested on both stable (LTS) and latest Jenkins versions.
 
 Known issues
 ------------
 * Job deletion operations fail unless Cross-Site scripting protection is disabled.
-
-For other issues, please refer to the support URL below.
+| For other issues, please refer to the `support URL <https://github.com/pycontribs/jenkinsapi/issues?direction=desc&sort=comments&state=open>`_
 
 Important Links
 ---------------
-
-Support and bug-reports: https://github.com/pycontribs/jenkinsapi/issues?direction=desc&sort=comments&state=open
-
-Project source code: github: https://github.com/pycontribs/jenkinsapi
-
-Project documentation: https://jenkinsapi.readthedocs.org/en/latest/
-
-Releases: http://pypi.python.org/pypi/jenkinsapi
+* `Support and bug-reports <https://github.com/pycontribs/jenkinsapi/issues?direction=desc&sort=comments&state=open>`_
+* `Source Code <https://github.com/pycontribs/jenkinsapi>`_
+* `Documentation <https://jenkinsapi.readthedocs.org/en/latest/>`_
+* `Releases <http://pypi.python.org/pypi/jenkinsapi>`_
 
 Installation
 -------------
@@ -114,20 +87,14 @@ JenkinsAPI is intended to map the objects in Jenkins (e.g. Builds, Views, Jobs)
 
 .. code-block:: python
 
-	>>> import jenkinsapi
-	>>> from jenkinsapi.jenkins import Jenkins
-	>>> J = Jenkins('http://localhost:8080')
-	>>> J.version
-	1.542
-	>>> J.keys() # Jenkins objects appear to be dict-like, mapping keys (job-names) to
-	['foo', 'test_jenkinsapi']
-	>>> J['test_jenkinsapi']
-	<jenkinsapi.job.Job test_jenkinsapi>
-	>>> J['test_jenkinsapi'].get_last_good_build()
-	<jenkinsapi.build.Build test_jenkinsapi #77>
-	...
-
-More examples available on Github: https://github.com/pycontribs/jenkinsapi/tree/master/examples
+	from jenkinsapi.jenkins import Jenkins
+	J = Jenkins('http://localhost:8080')
+	print(J.version) # 1.542
+	print(J.keys()) # foo, test_jenkinsapi
+	print(J.get('test_jenkinsapi')) # <jenkinsapi.job.Job test_jenkinsapi>
+	print(J.get('test_jenkinsapi').get_last_good_build()) # <jenkinsapi.build.Build test_jenkinsapi #77>
+
+More examples available on `Github <https://github.com/pycontribs/jenkinsapi/tree/master/examples>`_
 
 Testing
 -------
@@ -144,28 +111,41 @@ missing test dependencies:
 
 .. code-block:: bash
 
-    virtualenv
-    source .venv/bin/active
-    (venv) python setup.py test
+    python -m venv ./.venv/jenkinsapi
+    source .venv/jenkinsapi/bin/activate
+    pip install -r requirements.txt
+    python setup.py test
 
 Development
 -----------
 
-* Make sure that you have Java_ installed.
+* Make sure that you have Java_ installed. Jenkins will be automatically
+  downloaded and started during tests.
 * Create virtual environment for development
 * Install package in development mode
 
 .. code-block:: bash
 
-    (venv) pip install -e .
-    (venv) pip install -r test-requirements.txt
+    pip install -r test-requirements.txt
 
 * Make your changes, write tests and check your code
 
 .. code-block:: bash
 
-    (venv) tox
+    pytest -sv
+
+Python versions
+---------------
 
+The project has been tested against Python versions:
+
+* 3.8 - 3.13
+* 2.7 - last version compatible with Python 2.7 is tagged Py2 in repository and available on PyPi as version 0.3.13
+
+Jenkins versions
+----------------
+
+Project tested on both stable (LTS) and latest Jenkins versions.
 
 Project Contributors
 --------------------
@@ -194,4 +174,4 @@ The above copyright notice and this permission notice shall be included in all c
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-.. _Java: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html
+.. _Java: https://www.oracle.com/java/technologies/downloads/#java17

doc/source/rules_for_contributors.rst → doc/CONTRIBUTING.md

@@ -6,14 +6,17 @@ The JenkinsAPI project welcomes contributions via GitHub. Please bear in mind th
 Python compatibility
 --------------------
 
-The project currently targets Python 2.6 and Python 2.7. Support for Python 3.x will be introduced soon. Please do not add any features which
-will break our supported Python 2.x versions or make it harder for us to migrate to Python 3.x
+The project currently targets Python 3.8+. Last version compatible with Python 2.7 is tagged as Py2.
+
+Code formatting
+---------------
+
+The project follows strict PEP8 guidelines. Please use a tool like black to format your code before submitting a pull request. Tell black to use 79 characters per line (black -l 79).
 
 Test Driven Development
 -----------------------
 
-Please do not submit pull requests without tests. That's really important. Our project is all about test-driven development. It would be
-embarrasing if our project failed because of a lack of tests!
+Please do not submit pull requests without tests. That's really important. Our project is all about test-driven development. It would be embarrasing if our project failed because of a lack of tests!
 
 You might want to follow a typical test driven development cycle: http://en.wikipedia.org/wiki/Test-driven_development
 
@@ -24,7 +27,7 @@ Features implemented without tests will be removed. Unmaintained features (which
 Check the CI status before comitting
 ------------------------------------
 
-We have a Travis CI account - please verify that your branch works before making a pull request.
+Project uses Github Actions, please verify that your branch passes all tests before making a pull request.
 
 Any problems?
 -------------

doc/build.properties

@@ -1,3 +1,3 @@
 docs.zipfile.filename=docs_html.zip
 docs.html.dir=html
-docs.source.dir=source
+docs.source.dir=source