cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli/core/pagination.py

@@ -0,0 +1,131 @@
+"""Core pagination utilities."""
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+MAX_PAGE_SIZE = 1000
+
+
+class PageInfo:
+    """Data for pagination results."""
+
+    count = None
+    page = None
+    page_size = None
+    page_total = None
+
+    def __str__(self):
+        """Get page information as text."""
+        data = self.as_dict()
+        data["valid"] = self.is_valid
+        return (
+            "Valid: %(valid)s, Count: %(count)s, Page: %(page)s, "
+            "Size: %(page_size)s, Total: %(results_total)s" % data
+        )
+
+    def calculate_range(self, num_results):
+        """Calculate beginning and end of page range for results."""
+        if self.is_valid and num_results:
+            from_range = (self.page - 1) * self.page_size
+            to_range = from_range + num_results
+            from_range += 1
+        else:
+            from_range = 0
+            to_range = 0
+
+        return from_range, to_range
+
+    def as_dict(self, num_results=None):
+        """Create PageInfo from a dictionary."""
+        if not self.is_valid:
+            return {}
+
+        data = {
+            "results_total": self.count,
+            "page": self.page,
+            "page_size": self.page_size,
+            "page_max": self.page_total,
+        }
+
+        if num_results is not None:
+            from_range, to_range = self.calculate_range(num_results)
+            data["page_results_len"] = to_range - from_range
+            data["page_results_from"] = from_range
+            data["page_results_to"] = to_range
+
+        return data
+
+    @property
+    def is_valid(self):
+        """Check if the page information is valid."""
+        return all(
+            x is not None
+            for x in (self.count, self.page, self.page_size, self.page_total)
+        )
+
+    @classmethod
+    def from_headers(cls, headers):
+        """Create PageInfo from HTTP headers."""
+        info = PageInfo()
+
+        if "X-Pagination-Count" in headers:
+            info.count = int(headers["X-Pagination-Count"])
+        if "X-Pagination-Page" in headers:
+            info.page = int(headers["X-Pagination-Page"])
+        if "X-Pagination-PageSize" in headers:
+            info.page_size = int(headers["X-Pagination-PageSize"])
+        if "X-Pagination-PageTotal" in headers:
+            info.page_total = int(headers["X-Pagination-PageTotal"])
+
+        return info
+
+
+def paginate_results(
+    api_function: Callable[..., tuple[Sequence[Any], PageInfo]],
+    page_all: bool,
+    page: int,
+    page_size: int = MAX_PAGE_SIZE,
+    **kwargs: Any,
+) -> tuple[list[Any], PageInfo]:
+    """Retrieve paginated results.
+
+    Behaviour:
+    - If ``page_all`` is False: perform a single paged request and return the
+      results plus the (possibly invalid) ``PageInfo``. Single-resource API
+      endpoints frequently omit pagination headers; we tolerate that here.
+    - If ``page_all`` is True: iterate all pages requesting ``MAX_PAGE_SIZE``.
+      Missing pagination headers during aggregation are treated as a user
+      misuse (e.g. attempting ``--page-all`` against a single-resource
+      endpoint) and raise a ``click.ClickException`` for consistent UX.
+
+    Raises:
+        click.ClickException: If pagination headers are absent while trying to
+            aggregate multiple pages with ``page_all``.
+    """
+    if not page_all:
+        results, page_info = api_function(page=page, page_size=page_size, **kwargs)
+        # For single resource endpoints (e.g. repos_read) pagination headers may be absent.
+        # In that case we return the results with potentially invalid page_info (empty when serialized)
+        # rather than raising. Downstream pretty printers handle an invalid page_info gracefully.
+        return list(results), page_info
+
+    all_results: list[Any] = []
+    current_page = 1
+    last_page_info: PageInfo | None = None
+    while True:
+        page_results, last_page_info = api_function(
+            page=current_page, page_size=MAX_PAGE_SIZE, **kwargs
+        )
+        if not last_page_info.is_valid:
+            # No pagination headers (single-resource endpoint). Treat as single page.
+            # Return accumulated results without raising; command-level validators
+            # handle misuse of --page-all with single-resource endpoints.
+            all_results.extend(page_results)
+            return all_results, last_page_info
+        all_results.extend(page_results)
+
+        if current_page >= last_page_info.page_total:
+            break
+        current_page += 1
+
+    return all_results, last_page_info

cloudsmith_cli/core/ratelimits.py

@@ -0,0 +1,88 @@
+"""Core rate limit utilities."""
+
+import datetime
+import time
+
+
+class RateLimitsInfo:
+    """Data for rate limits."""
+
+    interval = None
+    limit = None
+    remaining = None
+    reset = None
+    throttled = None
+
+    def __str__(self):
+        """Get rate limit information as text."""
+        return (
+            "Throttled: %(throttled)s, Remaining: %(remaining)d/%(limit)d, "
+            "Interval: %(interval)f, Reset: %(reset)s"
+            % {
+                "throttled": "Yes" if self.throttled else "No",
+                "remaining": self.remaining,
+                "limit": self.limit,
+                "interval": self.interval,
+                "reset": self.reset,
+            }
+        )
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create RateLimitsInfo from a dictionary."""
+        info = RateLimitsInfo()
+
+        if "interval" in data:
+            info.interval = float(data["interval"])
+        if "limit" in data:
+            info.limit = int(data["limit"])
+        if "remaining" in data:
+            info.remaining = int(data["remaining"])
+        if "reset" in data:
+            info.reset = datetime.datetime.utcfromtimestamp(int(data["reset"]))
+        if "throttled" in data:
+            info.throttled = bool(data["throttled"])
+        else:
+            info.throttled = info.remaining == 0
+
+        return info
+
+    @classmethod
+    def from_headers(cls, headers):
+        """Create RateLimitsInfo from HTTP headers."""
+        try:
+            data = {
+                "interval": headers["X-RateLimit-Interval"],
+                "limit": headers["X-RateLimit-Limit"],
+                "remaining": headers["X-RateLimit-Remaining"],
+                "reset": headers["X-RateLimit-Reset"],
+            }
+        except KeyError:
+            data = {}
+
+        return cls.from_dict(data)
+
+
+def maybe_rate_limit(client, headers):
+    """Optionally pause the process based on suggested rate interval."""
+    rate_limit(client, headers)
+
+
+def rate_limit(client, headers):
+    """Pause the process based on suggested rate interval."""
+    if not client or not headers:
+        return False
+
+    if not getattr(client.config, "rate_limit", False):
+        return False
+
+    rate_info = RateLimitsInfo.from_headers(headers)
+    if not rate_info or not rate_info.interval:
+        return False
+
+    if rate_info.interval:
+        cb = getattr(client.config, "rate_limit_callback", None)
+        if cb and callable(cb):
+            cb(rate_info)
+        time.sleep(rate_info.interval)
+    return True

cloudsmith_cli/core/rest.py

@@ -0,0 +1,255 @@
+"""A RESTful API client with retry builtin."""
+
+import io
+import json
+import logging
+import re
+import time
+from urllib.parse import urlencode
+
+import requests
+import requests.exceptions
+from cloudsmith_api.configuration import Configuration
+from cloudsmith_api.rest import ApiException, RESTClientObject
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+logger = logging.getLogger(__name__)
+
+
+class RetryWithCallback(Retry):
+    """A urllib3 Retry with a callback on retries."""
+
+    def __init__(self, *args, **kwargs):
+        self.error_retry_cb = kwargs.pop("error_retry_cb", None)
+        super().__init__(*args, **kwargs)
+
+    def new(self, **kw):
+        kw["error_retry_cb"] = self.error_retry_cb
+        return super().new(**kw)
+
+    def sleep_for_retry(self, response=None):
+        retry_after = self.get_retry_after(response)
+        if retry_after:
+            self._sleep_with_callback(retry_after, context="retry-after")
+            return True
+
+        return False
+
+    def _sleep_backoff(self):
+        backoff = self.get_backoff_time()
+        if backoff <= 0:
+            return
+        self._sleep_with_callback(backoff, context="backoff")
+
+    def _sleep_with_callback(self, seconds, context=None):
+        """Sleep, but generate a callback before it."""
+        if self.error_retry_cb and callable(self.error_retry_cb):
+            self.error_retry_cb(seconds, context=context)
+        return time.sleep(seconds)
+
+
+def create_requests_session(
+    retries=None,
+    backoff_factor=None,
+    status_forcelist=None,
+    pools_size=4,
+    maxsize=4,
+    ssl_verify=None,
+    ssl_cert=None,
+    proxy=None,
+    session=None,
+    error_retry_cb=None,
+    respect_retry_after_header=True,
+    user_agent=None,
+    headers=None,
+):
+    """Create a requests session that retries some errors."""
+    # pylint: disable=too-many-branches
+    config = Configuration()
+
+    if retries is None:
+        retry_max = getattr(config, "error_retry_max", None)
+        retries = retry_max if retry_max is not None else 5
+
+    if backoff_factor is None:
+        retry_backoff = getattr(config, "error_retry_backoff", None)
+        backoff_factor = retry_backoff if retry_backoff is not None else 0.23
+
+    if status_forcelist is None:
+        retry_codes = getattr(config, "error_retry_codes", None)
+        status_forcelist = (
+            retry_codes if retry_codes is not None else [500, 502, 503, 504]
+        )
+
+    if ssl_verify is None:
+        ssl_verify = config.verify_ssl
+
+    if ssl_cert is None:
+        if config.cert_file and config.key_file:
+            ssl_cert = (config.cert_file, config.key_file)
+        elif config.cert_file:
+            ssl_cert = config.cert_file
+
+    if proxy is None:
+        proxy = Configuration().proxy
+
+    session = session or requests.Session()
+    session.verify = ssl_verify
+    session.cert = ssl_cert
+
+    if proxy:
+        session.proxies = {"http": proxy, "https": proxy}
+
+    retry = RetryWithCallback(
+        backoff_factor=backoff_factor,
+        connect=retries,
+        allowed_methods=False,
+        read=retries,
+        status_forcelist=tuple(status_forcelist),
+        status=retries,
+        total=retries,
+        error_retry_cb=error_retry_cb,
+        respect_retry_after_header=respect_retry_after_header,
+    )
+
+    adapter = HTTPAdapter(
+        max_retries=retry,
+        pool_connections=pools_size,
+        pool_maxsize=maxsize,
+        pool_block=True,
+    )
+
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+
+    if user_agent:
+        session.headers["User-Agent"] = user_agent
+
+    if headers:
+        session.headers.update(headers)
+
+    return session
+
+
+class RestResponse(io.IOBase):
+    """A urllib3 adapter for a requests response."""
+
+    def __init__(self, response):
+        super().__init__()
+        self.response = response
+        self.status = response.status_code
+        self.reason = response.reason
+        self._data = None
+
+    @property
+    def data(self):
+        """
+        Get the content for the response (lazily decoded).
+        """
+        if self._data is None:
+            self._data = self.response.content.decode("utf-8")
+        return self._data
+
+    def getheaders(self):
+        """
+        Return a dictionary of the response headers.
+        """
+        return self.response.headers
+
+    def getheader(self, name, default=None):
+        """
+        Return a given response header.
+        """
+        return self.response.headers.get(name, default)
+
+
+class RestClient(RESTClientObject):
+    """A rest client interface based on requests, with retry."""
+
+    def __init__(self, *args, **kwargs):
+        # pylint: disable=super-init-not-called
+        self.session = create_requests_session(*args, **kwargs)
+
+    def request(
+        self,
+        method,
+        url,
+        query_params=None,
+        headers=None,
+        body=None,
+        post_params=None,
+        _preload_content=True,
+        _request_timeout=None,
+    ):
+        """
+        :param method: http request method
+        :param url: http request url
+        :param query_params: query parameters in the url
+        :param headers: http request headers
+        :param body: request json body, for `application/json`
+        :param post_params: request post parameters,
+                            `application/x-www-form-urlencoded`
+                            and `multipart/form-data`
+        :param _preload_content: if False, the response object will be returned without
+                                 reading/decoding response data. Default is True.
+        :param _request_timeout: timeout setting for this request. If one number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of (connection, read) timeouts.
+        """
+        # Based on the RESTClientObject class generated by Swagger
+        method = method.upper()
+        assert method in ["GET", "HEAD", "DELETE", "POST", "PUT", "PATCH", "OPTIONS"]
+
+        post_params = post_params or {}
+        headers = headers or {}
+
+        if "Content-Type" not in headers:
+            headers["Content-Type"] = "application/json"
+
+        request_kwargs = {}
+
+        if query_params:
+            url += "?" + urlencode(query_params)
+
+        if method in ["POST", "PUT", "PATCH", "OPTIONS", "DELETE"]:
+            if re.search("json", headers["Content-Type"], re.IGNORECASE):
+                request_body = None
+                if body:
+                    request_body = json.dumps(body)
+                request_kwargs["data"] = request_body
+            elif headers["Content-Type"] == "application/x-www-form-urlencoded":
+                request_kwargs["data"] = post_params
+            elif headers["Content-Type"] == "multipart/form-data":
+                del headers["Content-Type"]
+                request_kwargs["data"] = post_params
+            elif isinstance(body, str):
+                request_kwargs["data"] = body
+            else:
+                # Cannot generate the request from given parameters
+                msg = """Cannot prepare a request message for provided arguments.
+                         Please check that your arguments match declared content type."""
+                raise ApiException(status=0, reason=msg)
+
+        try:
+            resp = self.session.request(
+                method,
+                url,
+                timeout=_request_timeout,
+                stream=not _preload_content,
+                headers=headers,
+                **request_kwargs,
+            )
+        except requests.exceptions.RequestException as exc:
+            msg = f"{type(exc).__name__}\n{str(exc)}"
+            raise ApiException(status=0, reason=msg)
+
+        resp.encoding = resp.apparent_encoding or "utf-8"
+        rest_resp = RestResponse(resp)
+
+        if _preload_content:
+            logger.debug("response body: %s", rest_resp.data)
+
+        if not 200 <= rest_resp.status <= 299:
+            raise ApiException(http_resp=rest_resp)
+
+        return rest_resp

cloudsmith_cli/core/utils.py

@@ -0,0 +1,95 @@
+"""Core utilities."""
+
+import hashlib
+import os
+
+import click
+
+
+def get_help_website():
+    """Get the URL for the help website."""
+    return "https://docs.cloudsmith.com/developer-tools/cli"
+
+
+def get_github_website():
+    """Get the URL for the GitHub project."""
+    return "https://github.com/cloudsmith-io/cloudsmith-cli"
+
+
+def get_root_path():
+    """Get the root directory for the application."""
+    return os.path.realpath(os.path.join(os.path.dirname(__file__), os.pardir))
+
+
+def get_data_path():
+    """Get the data directory for the application."""
+    return os.path.join(get_root_path(), "data")
+
+
+def read_file(*path):
+    """Read the specific file into a string in its entirety."""
+    real_path = os.path.realpath(os.path.join(*path))
+    with click.open_file(real_path, "r") as fp:
+        return fp.read()
+
+
+def calculate_file_md5(filepath, blocksize=2**20):
+    """Calculate an MD5 hash for a file."""
+    checksum = hashlib.md5(usedforsecurity=False)
+
+    with click.open_file(filepath, "rb") as f:
+
+        def update_chunk():
+            """Add chunk to checksum."""
+            buf = f.read(blocksize)
+            if buf:
+                checksum.update(buf)
+            return bool(buf)
+
+        while update_chunk():
+            pass
+
+    return checksum.hexdigest()
+
+
+def get_file_size(filepath):
+    """Get the size of a file in bytes."""
+    statinfo = os.stat(filepath)
+    return statinfo.st_size
+
+
+def get_page_kwargs(**kwargs):
+    """Construct page and page size kwargs (if present)."""
+    page_kwargs = {}
+
+    page = kwargs.get("page")
+    if page is not None and page > 0:
+        page_kwargs["page"] = page
+
+    page_size = kwargs.get("page_size")
+    if page_size is not None and page_size > 0:
+        page_kwargs["page_size"] = page_size
+
+    return page_kwargs
+
+
+def get_query_kwargs(**kwargs):
+    """Construct page and page size kwargs (if present)."""
+    query_kwargs = {}
+
+    query = kwargs.pop("query")
+    if query:
+        query_kwargs["query"] = query
+
+    return query_kwargs
+
+
+def get_sort_kwargs(**kwargs):
+    """Construct sort kwargs (if present)."""
+    sort_kwargs = {}
+
+    sort = kwargs.get("sort")
+    if sort:
+        sort_kwargs["sort"] = sort
+
+    return sort_kwargs

cloudsmith_cli/core/version.py

@@ -0,0 +1,20 @@
+"""Core version utilities."""
+
+import semver
+
+from . import utils
+
+
+def get_version():
+    """Get the raw/unparsed version of the application as a string."""
+    return utils.read_file(utils.get_data_path(), "VERSION").strip()
+
+
+def get_version_info():
+    """Get the application version as a VersionInfo object."""
+    return parse_version(get_version())
+
+
+def parse_version(version):
+    """Get a version string as a VersionInfo object."""
+    return semver.parse_version_info(version)

cloudsmith_cli/credential_helpers/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2026 Cloudsmith Ltd
+"""
+Credential helpers for various package managers.
+
+This package provides credential helper implementations for Docker, pip, npm, etc.
+Each helper follows its respective package manager's credential helper protocol.
+"""

cloudsmith_cli/credential_helpers/backends.py

@@ -0,0 +1,41 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Backend-kind enumeration for credential helpers."""
+
+from enum import IntEnum
+
+
+class BackendKind(IntEnum):
+    """Mirror of the server-side BackendKind enum (cloudsmith/package/enums.py)."""
+
+    DEB = 0
+    RPM = 1
+    RUBY = 2
+    PYTHON = 3
+    MAVEN = 4
+    BOWER = 5
+    DOCKER = 6
+    RAW = 7
+    CHOCOLATEY = 8
+    NPM = 9
+    NUGET = 10
+    VAGRANT = 11
+    COMPOSER = 12
+    ALPINE = 13
+    HELM = 14
+    CONAN = 15
+    CARGO = 16
+    LUAROCKS = 17
+    CRAN = 18
+    GO = 19
+    DART = 20
+    COCOAPODS = 21
+    TERRAFORM = 22
+    P2 = 23
+    CONDA = 24
+    HEX = 25
+    SWIFT = 26
+    HUGGINGFACE = 27
+    GENERIC = 28
+    VSX = 29
+    MCP = 30
+    DEFAULT = 99