diff --git a/GNUmakefile b/GNUmakefile index 64c4ea2..2f41029 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -162,7 +162,7 @@ help: @echo ' docs Generate Python sphinx documentation.' clean: - rm -rf build dist .ruff_cache + rm -rf build dist .ruff_cache docs/_build docs: sphinx-build -b html ./docs ./docs/_build diff --git a/docs/conf.py b/docs/conf.py index f33511e..65f7d66 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,21 +41,42 @@ project = 'libCSM' copyright = '2023, Cray / HPE' +master_doc = 'index' author = 'Russell Bunch, Mitchell Tishmack, Jacob Salmela' # -- General configuration --------------------------------------------------- extensions = [ 'sphinx.ext.autodoc', - 'sphinx_copybutton', + 'sphinx.ext.autosectionlabel', 'sphinx_autodoc_typehints', + 'sphinx_copybutton', + 'sphinx_rtd_theme', ] - +autosectionlabel_prefix_document = True templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] html_title = f"{project} Documentation ({version})" +locale_dirs = ['locale/'] # path is example but recommended. +language = 'en' +gettext_compact = False # optional. +versioning_conditions = ['text'] +add_function_parentheses = True +add_module_names = True # -- Options for HTML output ------------------------------------------------- -html_theme = 'alabaster' +html_show_sphinx = False +html_theme = "sphinx_rtd_theme" +html_theme_options = { + 'logo_only': False, + 'navigation_depth': 5, +} html_static_path = ['_static'] html_favicon = '_static/favicon.ico' html_logo = '_static/csm.jpeg' +html_context = { + 'display_github': True, + 'github_user': 'Cray-HPE', + 'github_repo': 'libCSM', + 'github_version': 'main', +} + diff --git a/docs/libcsm.api.rst b/docs/libcsm.api.rst new file mode 100644 index 0000000..7137321 --- /dev/null +++ b/docs/libcsm.api.rst @@ -0,0 +1,8 @@ +libcsm.api module +================= + +.. automodule:: libcsm.api + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.bss.api.rst b/docs/libcsm.bss.api.rst new file mode 100644 index 0000000..04cf96d --- /dev/null +++ b/docs/libcsm.bss.api.rst @@ -0,0 +1,11 @@ +libcsm.bss.api module +===================== + +Module contents +--------------- + +.. automodule:: libcsm.bss.api + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.bss.rst b/docs/libcsm.bss.rst new file mode 100644 index 0000000..14d9217 --- /dev/null +++ b/docs/libcsm.bss.rst @@ -0,0 +1,20 @@ +libcsm.bss package +================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.bss.api + libcsm.bss.set_image + +Module contents +--------------- + +.. automodule:: libcsm.bss + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.bss.set_image.rst b/docs/libcsm.bss.set_image.rst new file mode 100644 index 0000000..1b7d51b --- /dev/null +++ b/docs/libcsm.bss.set_image.rst @@ -0,0 +1,11 @@ +libcsm.bss.set_image module +=========================== + +Module contents +--------------- + +.. automodule:: libcsm.bss.set_image + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.hsm.components.rst b/docs/libcsm.hsm.components.rst new file mode 100644 index 0000000..604ea85 --- /dev/null +++ b/docs/libcsm.hsm.components.rst @@ -0,0 +1,11 @@ +libcsm.hsm.components module +============================ + +Module contents +--------------- + +.. automodule:: libcsm.hsm.components + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.hsm.rst b/docs/libcsm.hsm.rst new file mode 100644 index 0000000..1de006f --- /dev/null +++ b/docs/libcsm.hsm.rst @@ -0,0 +1,20 @@ +libcsm.hsm package +================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.hsm.components + libcsm.hsm.xnames + +Module contents +--------------- + +.. automodule:: libcsm.hsm + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.hsm.xnames.rst b/docs/libcsm.hsm.xnames.rst new file mode 100644 index 0000000..5b90c90 --- /dev/null +++ b/docs/libcsm.hsm.xnames.rst @@ -0,0 +1,11 @@ +libcsm.hsm.xnames module +======================== + +Module contents +--------------- + +.. automodule:: libcsm.hsm.xnames + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.logger.rst b/docs/libcsm.logger.rst new file mode 100644 index 0000000..e7401fa --- /dev/null +++ b/docs/libcsm.logger.rst @@ -0,0 +1,8 @@ +libcsm.logger module +==================== + +.. automodule:: libcsm.logger + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.os.rst b/docs/libcsm.os.rst new file mode 100644 index 0000000..3868267 --- /dev/null +++ b/docs/libcsm.os.rst @@ -0,0 +1,8 @@ +libcsm.os module +================ + +.. automodule:: libcsm.os + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.requests.rst b/docs/libcsm.requests.rst new file mode 100644 index 0000000..ae74b7e --- /dev/null +++ b/docs/libcsm.requests.rst @@ -0,0 +1,20 @@ +libcsm.requests package +======================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.requests.session + +Module contents +--------------- + +.. automodule:: libcsm.requests + :members: + :undoc-members: + :show-inheritance: + + diff --git a/docs/libcsm.requests.session.rst b/docs/libcsm.requests.session.rst new file mode 100644 index 0000000..2a1baab --- /dev/null +++ b/docs/libcsm.requests.session.rst @@ -0,0 +1,11 @@ +libcsm.requests.session module +============================== + +Module contents +--------------- + +.. automodule:: libcsm.requests.session + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.rst b/docs/libcsm.rst index e9e49be..6bf3653 100644 --- a/docs/libcsm.rst +++ b/docs/libcsm.rst @@ -1,11 +1,34 @@ -API Reference -============= +libcsm package +============== -.. automodule:: libcsm - :members: +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + libcsm.bss + libcsm.hsm + libcsm.requests + libcsm.s3 + libcsm.sls + libcsm.tests + +Submodules +----------- -``api`` -------- +.. toctree:: + :maxdepth: 4 + + libcsm.api + libcsm.os + libcsm.logger + +Module contents +--------------- + +.. automodule:: libcsm + :members: + :undoc-members: + :show-inheritance: -.. automodule:: libcsm.api - :members: diff --git a/docs/libcsm.s3.images.rst b/docs/libcsm.s3.images.rst new file mode 100644 index 0000000..9fee8c6 --- /dev/null +++ b/docs/libcsm.s3.images.rst @@ -0,0 +1,11 @@ +libcsm.s3.images module +======================= + +Module contents +--------------- + +.. automodule:: libcsm.s3.images + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.s3.rst b/docs/libcsm.s3.rst new file mode 100644 index 0000000..0332fe7 --- /dev/null +++ b/docs/libcsm.s3.rst @@ -0,0 +1,20 @@ +libcsm.s3 package +================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.s3.images + libcsm.s3.s3object + +Module contents +--------------- + +.. automodule:: libcsm.s3 + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.s3.s3object.rst b/docs/libcsm.s3.s3object.rst new file mode 100644 index 0000000..d3878e6 --- /dev/null +++ b/docs/libcsm.s3.s3object.rst @@ -0,0 +1,11 @@ +libcsm.s3.s3object module +========================= + +Module contents +--------------- + +.. automodule:: libcsm.s3.s3object + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.sls.api.rst b/docs/libcsm.sls.api.rst new file mode 100644 index 0000000..839bf3e --- /dev/null +++ b/docs/libcsm.sls.api.rst @@ -0,0 +1,11 @@ +libcsm.sls.api module +===================== + +Module contents +--------------- + +.. automodule:: libcsm.sls.api + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.sls.get_hostname.rst b/docs/libcsm.sls.get_hostname.rst new file mode 100644 index 0000000..2d74fe5 --- /dev/null +++ b/docs/libcsm.sls.get_hostname.rst @@ -0,0 +1,11 @@ +libcsm.sls.get_hostname module +============================== + +Module contents +--------------- + +.. automodule:: libcsm.sls.get_hostname + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.sls.get_xname.rst b/docs/libcsm.sls.get_xname.rst new file mode 100644 index 0000000..0ad87e7 --- /dev/null +++ b/docs/libcsm.sls.get_xname.rst @@ -0,0 +1,11 @@ +libcsm.sls.get_xname module +=========================== + +Module contents +--------------- + +.. automodule:: libcsm.sls.get_xname + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.sls.rst b/docs/libcsm.sls.rst new file mode 100644 index 0000000..d703c77 --- /dev/null +++ b/docs/libcsm.sls.rst @@ -0,0 +1,21 @@ +libcsm.sls package +================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.sls.api + libcsm.sls.get_hostname + libcsm.sls.get_xname + +Module contents +--------------- + +.. automodule:: libcsm.sls + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.bss.rst b/docs/libcsm.tests.bss.rst new file mode 100644 index 0000000..49f91e5 --- /dev/null +++ b/docs/libcsm.tests.bss.rst @@ -0,0 +1,20 @@ +libcsm.tests.bss package +======================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.tests.bss.test_api + libcsm.tests.bss.test_set_image + +Module contents +--------------- + +.. automodule:: libcsm.tests.bss + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.bss.test_api.rst b/docs/libcsm.tests.bss.test_api.rst new file mode 100644 index 0000000..12c0741 --- /dev/null +++ b/docs/libcsm.tests.bss.test_api.rst @@ -0,0 +1,12 @@ +libcsm.tests.bss.test_api module +================================ + + +Module contents +--------------- + +.. automodule:: libcsm.tests.bss.test_api + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.bss.test_set_image.rst b/docs/libcsm.tests.bss.test_set_image.rst new file mode 100644 index 0000000..e4b4157 --- /dev/null +++ b/docs/libcsm.tests.bss.test_set_image.rst @@ -0,0 +1,12 @@ +libcsm.tests.bss.test_set_image module +====================================== + + +Module contents +--------------- + +.. automodule:: libcsm.tests.bss.test_set_image + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.hsm.rst b/docs/libcsm.tests.hsm.rst new file mode 100644 index 0000000..c2e50fe --- /dev/null +++ b/docs/libcsm.tests.hsm.rst @@ -0,0 +1,20 @@ +libcsm.tests.hsm package +======================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.tests.hsm.test_api + libcsm.tests.hsm.test_xnames + +Module contents +--------------- + +.. automodule:: libcsm.tests.hsm + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.hsm.test_api.rst b/docs/libcsm.tests.hsm.test_api.rst new file mode 100644 index 0000000..d6b28c0 --- /dev/null +++ b/docs/libcsm.tests.hsm.test_api.rst @@ -0,0 +1,12 @@ +libcsm.tests.hsm.test_api module +================================ + + +Module contents +--------------- + +.. automodule:: libcsm.tests.hsm.test_api + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.hsm.test_xnames.rst b/docs/libcsm.tests.hsm.test_xnames.rst new file mode 100644 index 0000000..105248d --- /dev/null +++ b/docs/libcsm.tests.hsm.test_xnames.rst @@ -0,0 +1,12 @@ +libcsm.tests.hsm.test_xnames module +=================================== + + +Module contents +--------------- + +.. automodule:: libcsm.tests.hsm.test_xnames + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.mock_objects.mock_http.rst b/docs/libcsm.tests.mock_objects.mock_http.rst new file mode 100644 index 0000000..cd14d93 --- /dev/null +++ b/docs/libcsm.tests.mock_objects.mock_http.rst @@ -0,0 +1,12 @@ +libcsm.tests.mock_objects.mock_http module +========================================== + + +Module contents +--------------- + +.. automodule:: libcsm.tests.mock_objects.mock_http + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.mock_objects.mock_sls.rst b/docs/libcsm.tests.mock_objects.mock_sls.rst new file mode 100644 index 0000000..4cea4ad --- /dev/null +++ b/docs/libcsm.tests.mock_objects.mock_sls.rst @@ -0,0 +1,12 @@ +libcsm.tests.mock_objects.mock_sls module +========================================= + + +Module contents +--------------- + +.. automodule:: libcsm.tests.mock_objects.mock_sls + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.mock_objects.rst b/docs/libcsm.tests.mock_objects.rst new file mode 100644 index 0000000..750318f --- /dev/null +++ b/docs/libcsm.tests.mock_objects.rst @@ -0,0 +1,20 @@ +libcsm.tests.mock_objects package +================================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.tests.mock_objects.mock_http + libcsm.tests.mock_objects.mock_sls + +Module contents +--------------- + +.. automodule:: libcsm.tests.mock_objects + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.rst b/docs/libcsm.tests.rst new file mode 100644 index 0000000..c23ef7f --- /dev/null +++ b/docs/libcsm.tests.rst @@ -0,0 +1,32 @@ +libcsm.tests package +==================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + libcsm.tests.bss + libcsm.tests.hsm + libcsm.tests.mock_objects + libcsm.tests.s3 + libcsm.tests.sls + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.tests.test_api + libcsm.tests.test_os + +Module contents +--------------- + +.. automodule:: libcsm.tests + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.s3.rst b/docs/libcsm.tests.s3.rst new file mode 100644 index 0000000..b2acfb2 --- /dev/null +++ b/docs/libcsm.tests.s3.rst @@ -0,0 +1,20 @@ +libcsm.tests.s3 package +======================= + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.tests.s3.test_get_s3_image_info + libcsm.tests.s3.test_s3object + +Module contents +--------------- + +.. automodule:: libcsm.tests.s3 + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.s3.test_get_s3_image_info.rst b/docs/libcsm.tests.s3.test_get_s3_image_info.rst new file mode 100644 index 0000000..cd400c0 --- /dev/null +++ b/docs/libcsm.tests.s3.test_get_s3_image_info.rst @@ -0,0 +1,12 @@ +libcsm.tests.s3.test_get_s3_image_info module +============================================= + + +Module contents +--------------- + +.. automodule:: libcsm.tests.s3.test_get_s3_image_info + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.s3.test_s3object.rst b/docs/libcsm.tests.s3.test_s3object.rst new file mode 100644 index 0000000..809af52 --- /dev/null +++ b/docs/libcsm.tests.s3.test_s3object.rst @@ -0,0 +1,12 @@ +libcsm.tests.s3.test_s3object module +===================================== + + +Module contents +--------------- + +.. automodule:: libcsm.tests.s3.test_s3object + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.sls.rst b/docs/libcsm.tests.sls.rst new file mode 100644 index 0000000..b34f6b7 --- /dev/null +++ b/docs/libcsm.tests.sls.rst @@ -0,0 +1,21 @@ +libcsm.tests.sls package +======================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + libcsm.tests.sls.test_api + libcsm.tests.sls.test_get_hostname + libcsm.tests.sls.test_get_xname + +Module contents +--------------- + +.. automodule:: libcsm.tests.sls + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.sls.test_api.rst b/docs/libcsm.tests.sls.test_api.rst new file mode 100644 index 0000000..0658cb1 --- /dev/null +++ b/docs/libcsm.tests.sls.test_api.rst @@ -0,0 +1,12 @@ +libcsm.tests.sls.test_api module +================================ + + +Module contents +--------------- + +.. automodule:: libcsm.tests.sls.test_api + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.sls.test_get_hostname.rst b/docs/libcsm.tests.sls.test_get_hostname.rst new file mode 100644 index 0000000..45f8d4d --- /dev/null +++ b/docs/libcsm.tests.sls.test_get_hostname.rst @@ -0,0 +1,12 @@ +libcsm.tests.sls.test_get_hostname module +========================================= + + +Module contents +--------------- + +.. automodule:: libcsm.tests.sls.test_get_hostname + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.sls.test_get_xname.rst b/docs/libcsm.tests.sls.test_get_xname.rst new file mode 100644 index 0000000..08685a7 --- /dev/null +++ b/docs/libcsm.tests.sls.test_get_xname.rst @@ -0,0 +1,12 @@ +libcsm.tests.sls.test_get_xname module +====================================== + + +Module contents +--------------- + +.. automodule:: libcsm.tests.sls.test_get_xname + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.test_api.rst b/docs/libcsm.tests.test_api.rst new file mode 100644 index 0000000..96ae477 --- /dev/null +++ b/docs/libcsm.tests.test_api.rst @@ -0,0 +1,12 @@ +libcsm.tests.test_api module +============================ + + +Module contents +--------------- + +.. automodule:: libcsm.tests.test_api + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/libcsm.tests.test_os.rst b/docs/libcsm.tests.test_os.rst new file mode 100644 index 0000000..a6fc88d --- /dev/null +++ b/docs/libcsm.tests.test_os.rst @@ -0,0 +1,11 @@ +libcsm.tests.test_os module +=========================== + +Module contents +--------------- + +.. automodule:: libcsm.tests.test_os + :members: + :undoc-members: + :show-inheritance: + diff --git a/libcsm/bss/api.py b/libcsm/bss/api.py index 9e620bf..83dc481 100644 --- a/libcsm/bss/api.py +++ b/libcsm/bss/api.py @@ -37,8 +37,10 @@ class API: Class for providing API to interact with BSS. """ - def __init__(self, api_gateway_address="api-gw-service-nmn.local"): - + def __init__(self, api_gateway_address="api-gw-service-nmn.local") -> None: + """ + :param api_gateway_address: The hostname for the API gateway. + """ self.api_gateway_address = api_gateway_address self.bootparams_url = f'https://{self.api_gateway_address}/apis/bss/boot/v1/bootparameters' self._auth = api.Auth() @@ -48,6 +50,8 @@ def __init__(self, api_gateway_address="api-gw-service-nmn.local"): def get_bss_bootparams(self, xname: str) -> str: """ Get bootparameters from BSS for a specifed xname. + + :param xname: The XNAME to fetch boot parameters for. """ body = {'hosts': [xname]} try: @@ -64,9 +68,12 @@ def get_bss_bootparams(self, xname: str) -> str: f'{bss_response.status_code} from BSS.') return bss_response.json()[0] - def patch_bss_bootparams(self, xname : str, bss_json) -> None: + def patch_bss_bootparams(self, xname: str, bss_json: dict) -> None: """ Patch the bootparameters in BSS for a specified xname. + + :param xname: The XNAME to patch in BSS. + :param bss_json: The JSON to patch with. """ try: patch_response = self.session.patch(self.bootparams_url, @@ -88,6 +95,9 @@ def set_bss_image(self, xname: str, image_dict: dict) -> None: The inputs are the node's xname and a dictionary containing initrd, kernel, and roofs image paths that will be set in BSS. + + :param xname: The XNAME to set images for in BSS. + :param image_dict: The image properties to set. """ if 'initrd' not in image_dict or 'kernel' not in image_dict or 'rootfs' not in image_dict: raise ValueError(f"ERROR set_bss_image has inputs 'xname' and 'image_dictonary' where" \ diff --git a/libcsm/cli.py b/libcsm/cli.py deleted file mode 100644 index e69de29..0000000 diff --git a/libcsm/hsm/components.py b/libcsm/hsm/components.py index 1ab2fd5..a99c762 100644 --- a/libcsm/hsm/components.py +++ b/libcsm/hsm/components.py @@ -33,10 +33,14 @@ ROLE_SUBROLES = ["Management_Master", "Management_Worker", "Management_Storage"] -def get_components(role_subrole: str, api_gateway_address="api-gw-service-nmn.local") \ +def get_components(role_subrole: str, api_gateway_address: str = "api-gw-service-nmn.local") \ -> requests.Response: """ Get management components from HSM based on their role and subrole. + + :param role_subrole: The subrole in HSM to query under. + :param api_gateway_address: The hostname of the API gateway. + :returns: The HTTP response from the API gateway. """ auth = api.Auth() auth.refresh_token() diff --git a/libcsm/hsm/xnames.py b/libcsm/hsm/xnames.py index 347c44b..2547920 100644 --- a/libcsm/hsm/xnames.py +++ b/libcsm/hsm/xnames.py @@ -31,6 +31,9 @@ def get_by_role_subrole(role_subrole: str) -> List[str]: """ Get xnames by subrole from HSM. + + :param: role_subrole: The subrole to fetch components for. + :returns: A list of all components for the given ``role_subrole``. """ components_response = components.get_components(role_subrole) xnames = [] diff --git a/libcsm/requests/session.py b/libcsm/requests/session.py index 947f7db..4186318 100644 --- a/libcsm/requests/session.py +++ b/libcsm/requests/session.py @@ -22,7 +22,7 @@ # OTHER DEALINGS IN THE SOFTWARE. # """ -Common functions for working with requests.session in libCSM. +Common functions for working with ``requests.session`` in libCSM. """ from os import getenv @@ -30,9 +30,12 @@ import certifi -def get_session(crt_variable="REQUESTS_CA_BUNDLE") -> requests.Session: +def get_session(crt_variable: str = "REQUESTS_CA_BUNDLE") -> requests.Session: """ - Get a requests.session and set verify with crt_variable. + Get a ``requests.session`` and set verify with ``crt_variable``. + + :param crt_variable: Variable holding the certificate. + :returns: A ``requests.Session`` with the specified certificate. """ crt_path = getenv(crt_variable, certifi.where()) session = requests.Session() diff --git a/libcsm/s3/images.py b/libcsm/s3/images.py index ec4624f..c61ff6b 100644 --- a/libcsm/s3/images.py +++ b/libcsm/s3/images.py @@ -22,7 +22,7 @@ # OTHER DEALINGS IN THE SOFTWARE. # """ -Function to return rootfs,kernel,initrd image path given an image ID. +Function to return ``rootfs``, ``kernel``, and the ``initrd`` image path given an image ID. """ import json @@ -45,11 +45,20 @@ def get_s3_image_info(bucket_name, image_id, endpoint_url) -> dict: Retrieve the initrd, rootfs, and kernel image for an S3 bucket and image ID. This returns a dictionary + + .. code-block:: json + { - rootfs: "" - kernel: "" - initrd: "" - }. + "rootfs": "", + "kernel": "", + "initrd": "" + } + + :param bucket_name: Name of bucket. + :param image_id: ID of image. + :param endpoint_url: S3 endpoint. + :raises ImageFormatException: When an image is not found. + :returns: Dictionary of images. """ image_manifest = image_id + "/manifest.json" image_object = s3object.S3Object(bucket_name, image_manifest) diff --git a/libcsm/s3/s3object.py b/libcsm/s3/s3object.py index 5392f7f..23b2431 100644 --- a/libcsm/s3/s3object.py +++ b/libcsm/s3/s3object.py @@ -36,7 +36,7 @@ class RGWAdminException(Exception): """ - An exception for problems running radosgw-admin commands. + An exception for problems running ``radosgw-admin`` commands. """ def __init__(self, message) -> None: @@ -50,6 +50,10 @@ class S3Object: """ def __init__(self, bucket: str, object_name: str): + """ + :param bucket: The bucket to represent from S3. + :param object_name: The bisect name of the bucket. + """ self.bucket = bucket self.object_name = object_name self.owner = None @@ -60,6 +64,7 @@ def __init__(self, bucket: str, object_name: str): def verify_bucket_exists(self) -> None: """ Verify the bucket provided exists in s3. + :raises RGWAdminException: When the command fails. """ result = run_command(['radosgw-admin', 'bucket', 'list', '--bucket', self.bucket]) if result.return_code != 0: @@ -68,6 +73,8 @@ def verify_bucket_exists(self) -> None: def get_object_owner(self) -> None: """ Get the owner of an object. + + :raises RGWAdminException: When the command fails. """ result = run_command(['radosgw-admin', 'object', 'stat', '--object', self.object_name, \ '--bucket', self.bucket]) @@ -80,6 +87,8 @@ def get_object_owner(self) -> None: def get_creds(self) -> None: """ Get the credentials to access the object based on the owner. + + :raises RGWAdminException: When the command fails. """ if self.owner is None: self.get_object_owner() @@ -90,9 +99,12 @@ def get_creds(self) -> None: self._a_key = info['keys'][0]['access_key'] self._s_key = info['keys'][0]['secret_key'] - def get_object(self, endpoint_url="http://rgw-vip"): + def get_object(self, endpoint_url: str = "http://rgw-vip") -> boto3.session.Session: """ - Get the object from s3. Returns a ``bob3.resource.Object``. + Get the object from s3. Returns a ``boto3.resource.Object``. + + :param endpoint_url: The endpoint URL to get objects from. + :returns: The S3 object. """ if self._a_key is None or self._s_key is None: self.get_creds() diff --git a/libcsm/sls/api.py b/libcsm/sls/api.py index b3bc0f2..68e0915 100644 --- a/libcsm/sls/api.py +++ b/libcsm/sls/api.py @@ -36,8 +36,11 @@ class API: Class for providing API to interact with SLS. """ - def __init__(self, api_gateway_address="api-gw-service-nmn.local"): + def __init__(self, api_gateway_address: str = "api-gw-service-nmn.local"): + """ + :param api_gateway_address: The hostname of the API gateway. + """ self.api_gateway_address = api_gateway_address self.sls_url = f'https://{self.api_gateway_address}/apis/sls/v1/' self._auth = api.Auth() @@ -64,6 +67,9 @@ def get_management_components_from_sls(self) -> requests.Response: def get_xname(self, hostname: str) -> str: """ Get the xname of a node from SLS based on a provided hostname. + + :param hostname: The hostname to lookup. + :returns: The XNAME. """ try: components_response = (self.get_management_components_from_sls()).json() @@ -84,6 +90,9 @@ def get_xname(self, hostname: str) -> str: def get_hostname(self, xname: str) -> str: """ Get the hostname of a management node from SLS based on a provided xname. + + :param xname: The XNAME to lookup. + :returns: The hostname. """ try: components_response = (self.get_management_components_from_sls()).json() diff --git a/libcsm/sls/get_hostname.py b/libcsm/sls/get_hostname.py index 61eb349..014d2bc 100644 --- a/libcsm/sls/get_hostname.py +++ b/libcsm/sls/get_hostname.py @@ -36,11 +36,14 @@ help='xname of the node whose hostname should be returned.') @click.option('--api-gateway-address', required=False, type=str, default='api-gw-service-nmn.local', help='API gateway address. Default is \'api-gw-service-nmn.local\'.') -def main(xname, api_gateway_address) -> None: +def main(xname: str, api_gateway_address: str) -> None: """ Get the hostname of an NCN for a given Xname. This queries SLS for management nodes' information. + + :param xname: The XNAME to lookup. + :param api_gateway_address: The hostname of the API gateway. """ sls_api = api.API(api_gateway_address) try: diff --git a/libcsm/sls/get_xname.py b/libcsm/sls/get_xname.py index 3107e98..7032374 100644 --- a/libcsm/sls/get_xname.py +++ b/libcsm/sls/get_xname.py @@ -36,10 +36,13 @@ help='hostname of the node whose Xname should be returned.') @click.option('--api-gateway-address', required=False, type=str, default='api-gw-service-nmn.local', help='API gateway address. Default is \'api-gw-service-nmn.local\'.') -def main(hostname, api_gateway_address) -> None: +def main(hostname: str, api_gateway_address: str) -> None: """ Get the Xname of a NCN given a hostname. This queries SLS for management nodes' information. + + :param hostname: The hostname ot lookup. + :param api_gateway_address: The hostname of the API gateway. """ sls_api = api.API(api_gateway_address) try: diff --git a/pyproject.toml b/pyproject.toml index fed9dd0..e0c7deb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -62,9 +62,12 @@ ci = [ 'nox~=2023.4.22', ] docs = [ - 'sphinx~=6.1.3', + 'recommonmark~=0.7.1', + 'sphinx-autodoc-typehints~=1.24.0', 'sphinx-copybutton~=0.5.2', - 'sphinx-autodoc-typehints~=1.23.0', + 'sphinx-markdown-tables~=0.0.17', + 'sphinx-rtd-theme~=1.3.0', + 'sphinx~=7.2.2', ] lint = [ 'ruff~=0.0.280',