Skip to content

ci: updated build to work with most recent pdoc version #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 25, 2025
Merged

ci: updated build to work with most recent pdoc version #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 13 additions & 20 deletions .github/workflows/build.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ jobs:
- name: centos-stream-9
shortcut: c9s
container-name: el9stream
pip-command: pip3

name: ${{ matrix.name }}

Expand Down Expand Up @@ -86,15 +87,15 @@ jobs:
ref: 'gh-pages'

generate_documentation:
runs-on: ubuntu-20.04
runs-on: ubuntu-latest
steps:
- name: Install Dependencies
# This step installs dependencies for python-sdk and pdoc
run: |
sudo apt update &&
sudo apt install -y git \
python2 \
python2-dev \
python3 \
python3-dev \
curl \
asciidoctor \
gcc \
Expand All @@ -109,34 +110,26 @@ jobs:
- name: Checkout sources
uses: actions/checkout@v4

- name: Install pip2.7
# This step installs pip2.7, which will be needed later
run: |
curl https://bootstrap.pypa.io/pip/2.7/get-pip.py --output get-pip.py
python2 get-pip.py

- name: Install Python-SDK with Python 2.7
- name: Install Python-SDK with Python 3
# This step installs the python-sdk with python2.7, as the extension of pdoc,
# which is subsequently installed, doesn't have python3 support.
run: |
pip2.7 install setuptools
pip install setuptools
bash .automation/generate-setup-files.sh
python2.7 setup.py install --user --prefix=
python3 setup.py install --user --prefix=
shell: bash

- name: Install Pdoc
# This steps installs an extension of pdoc which supports asciidoc
# (this extension runs on python2).
run: |
git clone https://github.com/machacekondra/pdoc
cd pdoc
pip2.7 install -U .
pip install pdoc

- name: Install pygments
run: pip2.7 install pygments
run: pip install pygments

- name: Generate documentation
run: pdoc ovirtsdk4 --html --html-dir=html
run: pdoc ovirtsdk4 -o ./${{ env.GEN_DOC_DIR }} -t pdoc

- name: Upload generated documentation artifacts
uses: actions/upload-artifact@v4
Expand All @@ -157,7 +150,7 @@ jobs:
uses: actions/download-artifact@v4
with:
name: generated-documentation
path: ${{ env.GEN_DOC_DIR }}
path: ${{ env.GEN_DOC_DIR }}/

- name: Install package dependencies
run: |
Expand Down Expand Up @@ -197,8 +190,8 @@ jobs:

- name: Move created documentation to gh-pages
run: |
mkdir -p ./ovirt-engine-sdk/${{env.FOLDER}}/
cp ./html/ovirtsdk4/* ./ovirt-engine-sdk/${{env.FOLDER}}/
mkdir -p ./ovirt-engine-sdk/${{ env.FOLDER }}/
cp -r ./${{ env.GEN_DOC_DIR }}/* ./ovirt-engine-sdk/${{ env.FOLDER }}/

- name: Push changes to gh-pages
run: |
Expand Down
117 changes: 69 additions & 48 deletions lib/ovirtsdk4/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,11 @@
from urllib import urlencode
from urlparse import urlparse

from ovirtsdk4 import version
from ovirtsdk4.http import Response

def get_version():
from ovirtsdk4 import version
return version.VERSION

class Error(Exception):
"""
Expand All @@ -44,20 +46,22 @@ class Error(Exception):
def __init__(self, message, code=None, fault=None):
"""
Creates an instance of Error class.

`message`:: The exception message.

`code`:: An error code associated to the error. For HTTP related
errors, this will be the HTTP response code returned by the server.
For example, if retrieving of a virtual machine fails because it
doesn't exist this attribute will contain the integer value 404. Note
that this may be `nil` if the error is not HTTP related.

`fault`:: The `Fault` object associated to the error.
"""
super(Error, self).__init__(message)
"""
Creates an instance of Error class.
"""
self.code = code
"""
An error code associated to the error. For HTTP related
errors, this will be the HTTP response code returned by the server.
For example, if retrieving of a virtual machine fails because it
doesn't exist this attribute will contain the integer value 404. Note
that this may be `nil` if the error is not HTTP related."""
self.fault = fault
"""
The `Fault` object associated to the error.
"""


class AuthError(Error):
Expand Down Expand Up @@ -230,70 +234,87 @@ def __init__(

This method supports the following parameters:

`url`:: A string containing the base URL of the server, usually
`url` \n
A string containing the base URL of the server, usually
something like `https://server.example.com/ovirt-engine/api`.

`username`:: The name of the user, something like `admin@internal`.
`username` \n
The name of the user, something like `admin@internal`.

`password`:: The name password of the user.
`password` \n
The name password of the user.

`token`:: : The token to be used to access API. Optionally, user can
`token` \n
The token to be used to access API. Optionally, user can
use token, instead of username and password to access API. If user
don't specify `token` parameter, SDK will automatically create one.

`insecure`:: A boolean flag that indicates if the server TLS
`insecure` \n
A boolean flag that indicates if the server TLS
certificate and host name should be checked.

`ca_file`:: A PEM file containing the trusted CA certificates. The
`ca_file` \n
A PEM file containing the trusted CA certificates. The
certificate presented by the server will be verified using these CA
certificates. If `ca_file` parameter is not set, system wide
CA certificate store is used.

`debug`:: A boolean flag indicating if debug output should be
`debug` \n
A boolean flag indicating if debug output should be
generated. If the value is `True` and the `log` parameter isn't
`None` then the data sent to and received from the server will
be written to the log. Be aware that user names and passwords will
also be written, so handle it with care.

`log`:: The logger where the log messages will be written.
`log` \n
The logger where the log messages will be written.

`kerberos`:: A boolean flag indicating if Kerberos
`kerberos` \n
A boolean flag indicating if Kerberos
authentication should be used instead of the default basic
authentication.

`timeout`:: The maximum total time to wait for the response, in
`timeout` \n
The maximum total time to wait for the response, in
seconds. A value of zero (the default) means wait for ever. If
the timeout expires before the response is received an exception
will be raised.

`compress`:: A boolean flag indicating if the SDK should ask
`compress` \n
A boolean flag indicating if the SDK should ask
the server to send compressed responses. The default is `True`.
Note that this is a hint for the server, and that it may return
uncompressed data even when this parameter is set to `True`.
Note that compression will be disabled if user pass `debug`
parameter set to `true`, so the debug messages are in plain text.

`sso_url`:: A string containing the base SSO URL of the serve.
`sso_url` \n
A string containing the base SSO URL of the serve.
Default SSO url is computed from the `url` if no `sso_url` is provided.

`sso_revoke_url`:: A string containing the base URL of the SSO
`sso_revoke_url` \n
A string containing the base URL of the SSO
revoke service. This needs to be specified only when using
an external authentication service. By default this URL
is automatically calculated from the value of the `url` parameter,
so that SSO token revoke will be performed using the SSO service
that is part of the engine.

`sso_token_name`:: The token name in the JSON SSO response returned
`sso_token_name` \n
The token name in the JSON SSO response returned
from the SSO server. Default value is `access_token`.

`headers`:: A dictionary with headers which should be send with every
`headers` \n
A dictionary with headers which should be send with every
request.

`connections`:: The maximum number of connections to open to the host.
`connections` \n
The maximum number of connections to open to the host.
If the value is `0` (the default) then the number of connections will
be unlimited.

`pipeline`:: The maximum number of request to put in an HTTP pipeline
`pipeline` \n
The maximum number of request to put in an HTTP pipeline
without waiting for the response. If the value is `0` (the default)
then pipelining is disabled.
"""
Expand Down Expand Up @@ -360,7 +381,8 @@ def send(self, request):

This method supports the following parameters.

`request`:: The Request object containing the details of the HTTP
`request` \n
The Request object containing the details of the HTTP
request to send.

The returned value is a Request object containing the details of the
Expand Down Expand Up @@ -445,7 +467,7 @@ def __send(self, request):
for header_name, header_value in headers_dict.items():
header_lines.append('%s: %s' % (header_name, header_value))

header_lines.append('User-Agent: PythonSDK/%s' % version.VERSION)
header_lines.append('User-Agent: PythonSDK/%s' % get_version())
header_lines.append('Version: 4')
header_lines.append('Content-Type: application/xml')
header_lines.append('Accept: application/xml')
Expand Down Expand Up @@ -796,7 +818,7 @@ def close(self, logout=True):
"""
Releases the resources used by this connection.

`logout`:: A boolean, which specify if token should be revoked,
`logout` A boolean, which specify if token should be revoked,
and so user should be logged out.
"""

Expand All @@ -818,10 +840,10 @@ def _build_url(self, path='', query=None):

This method supports the following parameters:

`path`:: The path that will be added to the base URL. The default is an
`path` The path that will be added to the base URL. The default is an
empty string.

`query`:: A dictionary containing the query parameters to add to the
`query` A dictionary containing the query parameters to add to the
URL. The keys of the dictionary should be strings containing the names
of the parameters, and the values should be strings containing the
values.
Expand All @@ -841,7 +863,7 @@ def check_xml_content_type(self, response):
XML then it does nothing. If it isn't XML then it raises an
exception.

`response`:: The HTTP response to check.
`response` The HTTP response to check.
"""
return self._check_content_type(
self.__XML_CONTENT_TYPE_RE,
Expand All @@ -855,7 +877,7 @@ def check_json_content_type(self, response):
JSON then it does nothing. If it isn't JSON then it raises an
exception.

`response`:: The HTTP response to check.
`response` The HTTP response to check.
"""
return self._check_content_type(
self.__JSON_CONTENT_TYPE_RE,
Expand All @@ -868,10 +890,10 @@ def _check_content_type(self, expected_re, expected_name, headers):
Checks the given content type and raises an exception if it isn't the
expected one.

`expected_re`:: The regular expression used to check the expected
`expected_re` The regular expression used to check the expected
content type.
`expected_name`:: The name of the expected content type.
`headers`:: The HTTP headers to check.
`expected_name` The name of the expected content type.
`headers` The HTTP headers to check.
"""
content_type = self._get_header_value(headers, 'content-type')
if expected_re.match(content_type) is None:
Expand All @@ -892,7 +914,7 @@ def _read_reponse(self, context):
"""
Read the response.

`context`:: tuple which contains cur easy, response body,
`context` tuple which contains cur easy, response body,
response headers, original request
"""
# Extract the response code and body:
Expand Down Expand Up @@ -935,8 +957,8 @@ def _get_header_value(self, headers, name):
"""
Return header value by its name.

`headers`:: list of headers
`name`:: name of the header
`headers` list of headers
`name` name of the header
"""
return next(
(h.split(':')[1].strip() for h in headers if h.lower().startswith(name)),
Expand Down Expand Up @@ -984,8 +1006,7 @@ class ConnectionBuilder(object):
equivalent to calling the constructor of the `Connection`
class. Typical use will be like this:

[source,python]
----
```python
# Create the builder once:
builder = ConnectionBuilder(
url='https://enginer40.example.com/ovirt-engine/api',
Expand All @@ -1001,7 +1022,7 @@ class ConnectionBuilder(object):
# Create and use a second connection:
with builder.build() as connection:
...
----
```
"""

def __init__(self, **kwargs):
Expand Down Expand Up @@ -1029,7 +1050,7 @@ def build(self):
# import ovirtsdk4 as sdk
# vm = sdk.types.Vm()
#
from ovirtsdk4 import readers # noqa: F401
from ovirtsdk4 import services # noqa: F401
from ovirtsdk4 import types # noqa: F401
from ovirtsdk4 import writers # noqa: F401
import ovirtsdk4.readers as readers # noqa: F401
import ovirtsdk4.writers as writers # noqa: F401
import ovirtsdk4.types as types # noqa: F401
import ovirtsdk4.services as services # noqa: F401
Loading