From b4fccc889fe45776d1e7ab58b01abe3ff1b03752 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Tue, 13 Feb 2024 17:23:25 +0100
Subject: [PATCH] update docstrings
---
.pre-commit-config.yaml | 1 +
docs/source/glossary.rst | 3 ++
.../vocabularies/geant-jargon/accept.txt | 4 ++-
gso/auth/oidc_policy_helper.py | 36 +++++++------------
gso/auth/security.py | 4 +--
test/workflows/__init__.py | 2 +-
6 files changed, 21 insertions(+), 29 deletions(-)
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 70bfc27e..6c9492b7 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -9,6 +9,7 @@ repos:
- --fix
- --preview
- --ignore=PLR0917,PLR0914
+ - --extend-exclude=test/*
# Run the formatter.
- id: ruff-format
args:
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index 959d8976..0bbcce27 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -58,6 +58,9 @@ Glossary of terms
Simple Network Management Protocol: a protocol that's used for gathering data, widely used for network management
and monitoring.
+ TWAMP
+ Two-way Active Measurement Protocol.
+
UUID
Universally Unique Identifier
diff --git a/docs/vale/styles/config/vocabularies/geant-jargon/accept.txt b/docs/vale/styles/config/vocabularies/geant-jargon/accept.txt
index 081f7913..9172c42e 100644
--- a/docs/vale/styles/config/vocabularies/geant-jargon/accept.txt
+++ b/docs/vale/styles/config/vocabularies/geant-jargon/accept.txt
@@ -14,4 +14,6 @@ Dark_fiber
PHASE 1
[Mm]odify
AAI
-[M|m]iddleware
\ No newline at end of file
+[M|m]iddleware
+TWAMP
+Pydantic
diff --git a/gso/auth/oidc_policy_helper.py b/gso/auth/oidc_policy_helper.py
index 04e2fc8e..241641dc 100644
--- a/gso/auth/oidc_policy_helper.py
+++ b/gso/auth/oidc_policy_helper.py
@@ -82,13 +82,8 @@ class OIDCUserModel(dict):
if the attribute is one of the registered claims or raises an AttributeError
if the key is not found.
- Args:
- ----
- key: The attribute name to retrieve.
-
- Returns:
- -------
- The value of the attribute if it exists, otherwise raises AttributeError.
+ :param str key: The attribute name to retrieve.
+ :return: The value of the attribute if it exists, otherwise raises AttributeError.
"""
try:
return object.__getattribute__(self, key)
@@ -167,6 +162,7 @@ class OPAResult(BaseModel):
----------
- result (bool): Indicates whether the access request is allowed or denied.
- decision_id (str): A unique identifier for the decision made by OPA.
+
"""
result: bool = False
@@ -208,15 +204,10 @@ class OIDCUser(HTTPBearer):
This is used as a security module in Fastapi projects
- Args:
- ----
- request: Starlette request method.
- token: Optional value to directly pass a token.
-
- Returns:
- -------
- OIDCUserModel object.
+ :param Request request: Starlette request method.
+ :param str token: Optional value to directly pass a token.
+ :return: OIDCUserModel object.
"""
if not oauth2lib_settings.OAUTH2_ACTIVE:
return None
@@ -380,16 +371,12 @@ def opa_decision(
to authorize requests based on OPA policies. It utilizes OIDC for user information and makes a
call to the OPA service to determine authorization.
- Args:
- ----
- opa_url: URL of the Open Policy Agent service.
- oidc_security: An instance of OIDCUser for user authentication.
- auto_error: If True, automatically raises an HTTPException on authorization failure.
- opa_kwargs: Additional keyword arguments to be passed to the OPA input.
+ :param str opa_url: URL of the Open Policy Agent service.
+ :param OIDCUser oidc_security: An instance of OIDCUser for user authentication.
+ :param bool auto_error: If True, automatically raises an HTTPException on authorization failure.
+ :param Mapping[str, str] | None opa_kwargs: Additional keyword arguments to be passed to the OPA input.
- Returns:
- -------
- An asynchronous decision function that can be used as a dependency in FastAPI endpoints.
+ :return: An asynchronous decision function that can be used as a dependency in FastAPI endpoints.
"""
async def _opa_decision(
@@ -407,6 +394,7 @@ def opa_decision(
request: Request object that will be used to retrieve request metadata.
user_info: The OIDCUserModel object that will be checked
async_request: The :term:`httpx` client.
+
"""
if not (oauth2lib_settings.OAUTH2_ACTIVE and oauth2lib_settings.OAUTH2_AUTHORIZATION_ACTIVE):
return None
diff --git a/gso/auth/security.py b/gso/auth/security.py
index 16065e46..e1d53764 100644
--- a/gso/auth/security.py
+++ b/gso/auth/security.py
@@ -34,8 +34,6 @@ def get_oidc_user() -> OIDCUser:
This function returns the instance of OIDCUser initialized in the module.
It is typically used for accessing the OIDCUser across different parts of the application.
- Returns
- -------
- OIDCUser: The instance of OIDCUser configured with OAuth2 settings.
+ :return OIDCUser: The instance of OIDCUser configured with OAuth2 settings.
"""
return oidc_user
diff --git a/test/workflows/__init__.py b/test/workflows/__init__.py
index 669fd75c..5470858c 100644
--- a/test/workflows/__init__.py
+++ b/test/workflows/__init__.py
@@ -140,7 +140,7 @@ class WorkflowInstanceForTests(LazyWorkflowInstance):
This can be as simple as merely importing a workflow function. However, if it concerns a workflow generating
function, that function will be called with or without arguments as specified.
- Returns: A workflow function.
+ :return Workflow: A workflow function.
"""
self.workflow.name = self.name
return self.workflow
--
GitLab