pdmv-http-client 2.1.0__py3-none-any.whl

pdmv_http_client-2.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: pdmv-http-client
+Version: 2.1.0
+Summary: A HTTP client wrapper to handle authenticated requests to CERN internal applications
+Maintainer-email: PdmV Service <pdmv.service@cern.ch>, PPD Technical Support <cms-PPD-technical-support@cern.ch>
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.cern.ch/cms-ppd/technical-support/libraries/pdmv-http-client
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.5
+Dynamic: license-file
+
+# PdmV HTTP Client
+
+This project provides an HTTP client based on [requests](https://github.com/psf/requests) to handle authenticated requests to CERN
+internal applications. Furthermore, it includes some clients to ease the interaction with the APIs of
+PdmV applications. This version is a refactor of the old [McM Scripts](https://github.com/cms-PdmV/mcm_scripts) project, and it is published at
+PyPI to be public available.
+
+### How to use this package
+
+#### Prerequisite
+
+Create an isolated virtual environment using a Python version >= 3.9 like, for instance:
+
+`python3.9 -m venv venv && source ./venv/bin/activate`
+
+#### Development version
+
+If you want to set up a development environment to contribute to this project:
+
+Install `uv` and the required dependencies.
+
+`pip install uv`
+
+Set the current `venv` to use with `uv`:
+
+`export UV_PROJECT_ENVIRONMENT="${VIRTUAL_ENV}"`
+
+Install the packages via: `uv sync`
+
+Run the test suite via:
+`uv run pytest -s -vv`
+
+> [!IMPORTANT]
+> Make sure your execution environment has a valid Kerberos ticket to consume CERN services!
+
+#### Build package
+
+If you just want to use this package in your own project, install it via:
+
+`pip install pdmv-http-client`
+
+Make sure to remove the `sys.path.append(...)` statement, if you have them in your script, to avoid overloading old versions from CERN AFS.
+
+### Examples
+
+At the `examples/` folder, you will find some scripts explaining how to use the clients and the HTTP client.
+
+### Priority change
+* If you want to use priority-changing scripts or do anything else related to cmsweb, you'll have to use voms-proxy:
+    * `voms-proxy-init -voms cms`
+    * `export X509_USER_PROXY=$(voms-proxy-info --path)`

pdmv_http_client-2.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+pdmv_http_client-2.1.0.dist-info/licenses/LICENSE,sha256=RYl3foijZoW2abvncpHax5Prn4sgcSFNuqMBVylpsqU,1083
+rest/__init__.py,sha256=4acKnG3HT8j7UDNpvvjTRh5aidulJmlvHQ43L1AKjqQ,315
+rest/_version.py,sha256=6G8yJbldQAMT0M9ZiFAqGo5OVqUMxGB1aeWeKmrwNIE,704
+rest/applications/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rest/applications/base.py,sha256=uKwX1Xd2PfiuBDM90bz2EnXsuYiHbUTCBb7c1uwR0OU,8865
+rest/applications/mcm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rest/applications/mcm/core.py,sha256=3RbNac2Y3fEEJc3KhqUImk4jzTSMQE6JvEkoC2A_GLw,9465
+rest/applications/mcm/invalidate_request.py,sha256=IfxTG5j0NToNQQNm93XqEjReuFDfnOrKtbws8_bDLuQ,15679
+rest/applications/mcm/resubmission.py,sha256=-5ScoFBAS7qKlbBe5sHu_QQ7aRAe8ilNMqTgN7SfwDY,17531
+rest/applications/rereco/core.py,sha256=g1jZpY_NMG2LpXlRdgu48kYrD2MGoNwDtakjhaAVMZI,2243
+rest/applications/stats/core.py,sha256=Bm7kZNrTMCwyBS7cgo8bcUb16u-U9FjGKrleJolGXhM,2737
+rest/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rest/client/session.py,sha256=S94lXzlNE_73V65WgOv6OJwVMf_l-ErJLCsIg-oPRrg,3224
+rest/client/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rest/client/auth/auth_interface.py,sha256=z4aQaJyZNcHkyiWgLD27eyTeeDF0Z1cLAG6xIF6oEj4,3204
+rest/client/auth/handlers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rest/client/auth/handlers/oauth2_tokens.py,sha256=kXpky06oQzMupuZl-ZOb3PG0STNLbeRulI-hwrzcT-E,10889
+rest/client/auth/handlers/session_cookies.py,sha256=a4-UZSAkNrlAGdE4lhPw2wVZvcXNysHtyHq3usMZzys,3695
+rest/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rest/utils/logger.py,sha256=OOE7ktIERtV91_GuxUKmLz9c6RQR_tcZ1ugdkeG2wZM,1013
+rest/utils/miscellaneous.py,sha256=r6Wmf6M3W1oZX41d0pj_4yqg8VoSncXTkAAEyk228_g,1247
+rest/utils/shell.py,sha256=HlUjyLZbhkKoktR0um4Ig4cNI1F0sLEc5xvjc2xHILQ,1438
+pdmv_http_client-2.1.0.dist-info/METADATA,sha256=LarL6koytstCDOI6SriHoRTuJjYY3akJ7hptP5oeDNU,2431
+pdmv_http_client-2.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdmv_http_client-2.1.0.dist-info/top_level.txt,sha256=0QXYxm_ASalsWNLMGOoXHpjHuompr6ZCXwA-QrTZCZE,5
+pdmv_http_client-2.1.0.dist-info/RECORD,,

pdmv_http_client-2.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pdmv_http_client-2.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The CMS PPD Technical Team
+
+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.

pdmv_http_client-2.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rest

rest/__init__.py

@@ -0,0 +1,10 @@
+"""
+Exposes the REST client for the McM application
+like the old structure used to do.
+Just to keep backward compatibility.
+"""
+
+from rest.applications.base import BaseClient
+from rest.applications.mcm.core import McM
+from rest.applications.rereco.core import ReReco
+from rest.applications.stats.core import Stats2

rest/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '2.1.0'
+__version_tuple__ = version_tuple = (2, 1, 0)
+
+__commit_id__ = commit_id = None

rest/applications/base.py

@@ -0,0 +1,238 @@
+"""
+REST client default structure.
+This sets the default schema for creating a HTTP client
+object for PdmV applications.
+"""
+
+import os
+from pathlib import Path
+from typing import Union
+
+import requests
+
+from rest.client.session import SessionFactory
+from rest.utils.logger import LoggerFactory
+from rest.utils.shell import describe_platform
+
+
+class BaseClient:
+    """
+    Configures the internal HTTP client session.
+    """
+
+    # Authentication mechanisms
+    SSO = "sso"
+    OIDC = "oidc"
+    OAUTH = "oauth2"
+    COOKIE_ENV_VAR = "PDMV_COOKIE_PATH"
+
+    def __init__(
+        self,
+        app: str,
+        id: str = SSO,
+        debug: bool = False,
+        cookie: Union[str, None] = None,
+        dev: bool = True,
+        client_id: str = "",
+        client_secret: str = "",
+    ):
+        """
+        Initializes the HTTP client session configuring the
+        authentication approach and the logger.
+
+        Arguments:
+            app: PdmV application's endpoint. This is used to
+                construct the target URL.
+
+            id: The authentication mechanism to use. Supported values are:
+                'sso': Request Session cookies via CERN 'auth-get-sso-cookie'
+                    package. This approach does not work if the user's account
+                    enforces 2FA. Make sure to provide a Kerberos ticket to consume
+                    CERN resources in your runtime environment.
+                'oidc': Request an ID token via Device Authorization Grant to consume
+                    resources. This requires human input to complete the flow.
+                'oauth': Request an Access token via Client Credentials Grant to consume
+                    resources. This requires the user to provide the `client_id` and `client_secret`
+                    to requests tokens. Please see the `API Access` tutorial in CERN
+                    Authentication docs for more details.
+
+                Otherwise, the HTTP session will be configured with no credentials.
+
+            debug: Logger's level.
+            cookie: The target path to store/load the credential. This is a legacy
+                argument from the old McM REST client. To keep compatibility, the name
+                of the argument remains the same.
+            dev: Whether to use the dev or production instance.
+            client_id: This is an optional argument only used if `id = OAUTH`, this
+                is the client ID for requesting an access token.
+            client_secret: This is an optional argument only used if `id = OAUTH`, this
+                is the client secret for requesting an access token.
+        """
+        self._app = app
+        self._id = id
+        self._debug = debug
+        self._cookie = cookie
+        self._dev = dev
+        self._client_id = client_id
+        self._client_secret = client_secret
+
+        self.logger = LoggerFactory.getLogger(f"pdmv-http-client.{self._app}")
+        self.server = self._target_web_application()
+        self.credentials_path: Union[Path, None] = None
+        self.session = self._create_session()
+
+    def _target_web_application(self) -> str:
+        """
+        Sets the production or development web application URL.
+        """
+        if self._dev:
+            return f"https://cms-pdmv-dev.web.cern.ch/{self._app}/"
+
+        return f"https://cms-pdmv-prod.web.cern.ch/{self._app}/"
+
+    def _credential_name(self) -> str:
+        """
+        Provides the credential's file name.
+        """
+        suffix = "credential-dev" if self._dev else "credential-prod"
+        prefix = self._app
+        return f"{prefix}-{suffix}"
+
+    def _credentials_path(self) -> Path:
+        """
+        Sets the path from which credentials are going to be loaded and saved.
+        """
+        # If a path is provided in the `cookie` argument, use it.
+        if self._cookie:
+            self.logger.info(
+                "Settting the credential's path (%s) as provided in arguments",
+                self._cookie,
+            )
+            return Path(self._cookie)
+
+        # If the user attempts to force the `cookie` argument
+        # via runtime variables, use it.
+        from_env_var = os.getenv(self.COOKIE_ENV_VAR)
+        if from_env_var:
+            self.logger.info(
+                "Settting the credential's path (%s) from environment variables",
+                from_env_var,
+            )
+            return Path(from_env_var)
+
+        # Otherwise, use a `private` folder in the user's home
+        # to create the credential.
+        private_folder = Path.home() / Path("private")
+        private_folder.mkdir(mode=0o700, exist_ok=True)
+        path = private_folder / Path(self._credential_name())
+        self.logger.info("Setting default credential's path (%s)", path)
+
+        return path
+
+    def _create_session(self) -> requests.Session:
+        """
+        Configures the HTTP session depending on the chosen authentication method.
+        """
+        session: Union[requests.Session, None] = None
+        if self._id == self.SSO:
+            self.credentials_path = self._credentials_path()
+            session = SessionFactory.configure_by_session_cookie(
+                url=self.server, credential_path=self.credentials_path
+            )
+        elif self._id == self.OIDC:
+            self.credentials_path = self._credentials_path()
+            target_application = "cms-ppd-pdmv-device-flow"
+            session = SessionFactory.configure_by_id_token(
+                url=self.server,
+                credential_path=self.credentials_path,
+                target_application=target_application,
+            )
+        elif self._id == self.OAUTH:
+            self.credentials_path = self._credentials_path()
+            target_application = "cms-ppd-pdmv-dev" if self._dev else "cms-ppd-pdmv"
+            session = SessionFactory.configure_by_access_token(
+                url=self.server,
+                credential_path=self.credentials_path,
+                target_application=target_application,
+                client_id=self._client_id,
+                client_secret=self._client_secret,
+            )
+        else:
+            self.logger.warning("Using HTTP client without providing authentication")
+            session = requests.Session()
+
+        # Include some headers for the session
+        user_agent = {
+            "User-Agent": f"PdmV HTTP client (For: {self._app}): {describe_platform()}"
+        }
+        session.headers.update(user_agent)
+        return session
+
+    def __repr__(self):
+        return f"<HTTP client (For: {self._app}) id: {self._id} server: {self.server} credential: {self.credentials_path}>"
+
+    def _get(self, url: str):
+        """
+        Performs a GET request to the target resource.
+        This assumes the target resource's response format is JSON.
+
+        Args:
+            url: Resource URL. Do not include a slash at the beginning.
+                For example: restapi/requests/get/B2G-Run3Summer22wmLHEGS-00033.
+
+        Returns:
+            Target resource response.
+        """
+        full_url = f"{self.server}{url}"
+        response = self.session.get(url=full_url)
+        return response.json()
+
+    def _put(self, url: str, data: dict):
+        """
+        Performs a PUT request to the target resource.
+        This assumes the target resource's response format is JSON.
+
+        Args:
+            url: Resource URL. Do not include a slash at the beginning.
+                For example: restapi/requests/get/B2G-Run3Summer22wmLHEGS-00033.
+            data: Request's body.
+
+        Returns:
+            Target resource response.
+        """
+        full_url = f"{self.server}{url}"
+        response = self.session.put(url=full_url, json=data)
+        return response.json()
+
+    def _post(self, url: str, data: dict):
+        """
+        Performs a POST request to the target resource.
+        This assumes the target resource's response format is JSON.
+
+        Args:
+            url: Resource URL. Do not include a slash at the beginning.
+                For example: restapi/requests/get/B2G-Run3Summer22wmLHEGS-00033.
+            data: Request's body.
+
+        Returns:
+            Target resource response.
+        """
+        full_url = f"{self.server}{url}"
+        response = self.session.post(url=full_url, json=data)
+        return response.json()
+
+    def _delete(self, url: str):
+        """
+        Performs a DELETE request to the target resource.
+        This assumes the target resource's response format is JSON.
+
+        Args:
+            url: Resource URL. Do not include a slash at the beginning.
+                For example: restapi/requests/get/B2G-Run3Summer22wmLHEGS-00033.
+
+        Returns:
+            Target resource response.
+        """
+        full_url = f"{self.server}{url}"
+        response = self.session.delete(url=full_url)
+        return response.json()