clear-skies-gitlab 2.0.4__tar.gz → 2.0.5__tar.gz

{clear_skies_gitlab-2.0.4 → clear_skies_gitlab-2.0.5}/CHANGELOG.md

@@ -5,9 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.5] - 2026-01-28
+
+### Changed
+- Update all classes to have documentation
+- Update to latest dependencies
+
 ## [2.0.4] - 2026-01-26
 
 ### Changed
+- Bump version to v2.0.4 by @github-actions[bot]
 - Update to latest copier version
 - Update to latest copier version
 - Update to latest copier version
@@ -45,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## New Contributors
 * @github-actions[bot] made their first contribution
 * @ made their first contribution
+[2.0.5]: https://github.com/clearskies-py/gitlab/compare/v2.0.4..v2.0.5
 [2.0.4]: https://github.com/clearskies-py/gitlab/compare/v2.0.3..v2.0.4
 [2.0.3]: https://github.com/clearskies-py/gitlab/compare/v2.0.2..v2.0.3
 [2.0.2]: https://github.com/clearskies-py/gitlab/compare/v2.0.1..v2.0.2

clear_skies_gitlab-2.0.5/LATEST_CHANGELOG.md

@@ -0,0 +1,6 @@
+## [2.0.5] - 2026-01-28
+
+### Changed
+- Update all classes to have documentation
+- Update to latest dependencies
+

{clear_skies_gitlab-2.0.4 → clear_skies_gitlab-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clear-skies-gitlab
-Version: 2.0.4
+Version: 2.0.5
 Summary: Gitlab module for Clearskies
 Project-URL: Docs, https://https://clearskies.info/modules/clear-skies-gitlab
 Project-URL: Repository, https://github.com/clearskies-py/gitlab

{clear_skies_gitlab-2.0.4 → clear_skies_gitlab-2.0.5}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "clear-skies-gitlab"
 description = "Gitlab module for Clearskies"
-version = "2.0.4"
+version = "2.0.5"
 license = "MIT"
 readme = "./README.md"
 authors = [{name = "Tom Nijboer", email = "tom.nijboer@cimpress.com"}]

clear_skies_gitlab-2.0.5/src/clearskies_gitlab/defaults/gitlab_default_auth.py

@@ -0,0 +1,41 @@
+import clearskies
+
+
+class GitlabDefaultAuth(clearskies.di.AdditionalConfigAutoImport):
+    """
+    Dependency injection provider for GitLab authentication.
+
+    This class automatically provides GitLab authentication credentials to the
+    dependency injection container. It reads the authentication token from the
+    `GITLAB_AUTH_KEY` environment variable and configures a Bearer token
+    authentication handler.
+
+    The authentication is used by the GitlabRestBackend to authenticate API
+    requests to GitLab.
+
+    ```python
+    # Set environment variable with your GitLab personal access token
+    # export GITLAB_AUTH_KEY=glpat-xxxxxxxxxxxxxxxxxxxx
+
+    from clearskies_gitlab.rest.backends import GitlabRestBackend
+
+
+    class MyModel(clearskies.Model):
+        backend = GitlabRestBackend()
+        # Will automatically use the configured authentication
+    ```
+
+    The token should be a GitLab Personal Access Token (PAT) or Project/Group
+    Access Token with appropriate scopes for the API operations you need to perform.
+    """
+
+    def provide_gitlab_auth(self, environment: clearskies.Environment):
+        """
+        Provide the GitLab authentication handler from environment.
+
+        Reads the `GITLAB_AUTH_KEY` environment variable and returns a
+        SecretBearer authentication handler configured with the `Bearer ` prefix
+        as required by the GitLab API.
+        """
+        secret_key = environment.get("GITLAB_AUTH_KEY", True)
+        return clearskies.authentication.SecretBearer(secret_key=secret_key, header_prefix="Bearer ")

clear_skies_gitlab-2.0.5/src/clearskies_gitlab/defaults/gitlab_default_host.py

@@ -0,0 +1,39 @@
+import clearskies
+
+
+class GitlabDefaultHost(clearskies.di.AdditionalConfigAutoImport):
+    """
+    Dependency injection provider for the GitLab host URL.
+
+    This class automatically provides the GitLab host URL to the dependency
+    injection container. It reads the host from the `GITLAB_HOST` environment
+    variable, falling back to `https://gitlab.com/` if not set.
+
+    This is used by the GitlabRestBackend and other GitLab-related classes
+    to determine which GitLab instance to connect to.
+
+    ```python
+    # Set environment variable for self-hosted GitLab
+    # export GITLAB_HOST=https://gitlab.mycompany.com/
+
+    # Or use the default gitlab.com
+    # (no environment variable needed)
+
+    from clearskies_gitlab.rest.backends import GitlabRestBackend
+
+
+    class MyModel(clearskies.Model):
+        backend = GitlabRestBackend()
+        # Will automatically use the configured host
+    ```
+    """
+
+    def provide_gitlab_host(self, environment: clearskies.Environment):
+        """
+        Provide the GitLab host URL from environment or default.
+
+        Reads the `GITLAB_HOST` environment variable. If not set or empty,
+        returns the default GitLab.com URL.
+        """
+        gitlab_host = environment.get("GITLAB_HOST", True)
+        return gitlab_host if gitlab_host else "https://gitlab.com/"

clear_skies_gitlab-2.0.5/src/clearskies_gitlab/rest/backends/gitlab_rest_backend.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from urllib import parse
+
+from clearskies import configs
+from clearskies.backends import ApiBackend
+from clearskies.decorators import parameters_to_properties
+from clearskies.di import inject
+from clearskies.query import Query
+from clearskies.query.result import CountQueryResult
+from requests.structures import CaseInsensitiveDict
+
+if TYPE_CHECKING:
+    from clearskies.authentication import Authentication
+    from clearskies.query import Query
+
+
+class GitlabRestBackend(ApiBackend):
+    """
+    Backend for interacting with the GitLab REST API.
+
+    This backend extends the clearskies ApiBackend to provide GitLab-specific functionality
+    for making REST API calls to GitLab.com or self-hosted GitLab instances. It handles
+    authentication, pagination, and response mapping automatically.
+
+    The backend uses dependency injection to obtain the GitLab host URL and authentication
+    credentials, making it easy to configure for different environments.
+
+    ```python
+    import clearskies
+    from clearskies_gitlab.rest.backends import GitlabRestBackend
+
+
+    class MyGitlabModel(clearskies.Model):
+        backend = GitlabRestBackend()
+        id_column_name = "id"
+
+        id = clearskies.columns.Integer()
+        name = clearskies.columns.String()
+    ```
+
+    The backend automatically constructs the base URL using the configured GitLab host
+    and appends `/api/v4` for the REST API version.
+    """
+
+    """
+    Whether this backend supports count operations.
+
+    GitLab REST API supports counting via the `x-total` response header,
+    so this is set to True.
+    """
+    can_count = True
+
+    """
+    The GitLab host URL injected from the dependency container.
+
+    This is typically set via the `GITLAB_HOST` environment variable or through
+    explicit configuration. Defaults to `https://gitlab.com/` if not specified.
+    """
+    gitlab_host = inject.ByName("gitlab_host", cache=True)  # type: ignore[assignment]
+
+    """
+    The authentication handler injected from the dependency container.
+
+    This is typically configured via the `GITLAB_AUTH_KEY` environment variable
+    which provides a bearer token for API authentication.
+    """
+    authentication = inject.ByName("gitlab_auth", cache=False)  # type: ignore[assignment]
+
+    """
+    The requests handler for making HTTP calls.
+    """
+    requests = inject.Requests()
+
+    _auth_headers: dict[str, str] = {}
+
+    """
+    A mapping from API response field names to model field names.
+
+    Use this to handle cases where the GitLab API returns fields with different
+    names than your model expects.
+    """
+    api_to_model_map = configs.AnyDict(default={})
+
+    """
+    The name of the query parameter used for pagination.
+
+    GitLab uses `page` for page-based pagination.
+    """
+    pagination_parameter_name = configs.String(default="page")
+
+    @parameters_to_properties
+    def __init__(
+        self,
+        base_url: str | None = None,
+        authentication: Authentication | None = None,
+        model_casing: str = "snake_case",
+        api_casing: str = "snake_case",
+        api_to_model_map: dict[str, str | list[str]] = {},
+        pagination_parameter_name: str = "page",
+        pagination_parameter_type: str = "str",
+        limit_parameter_name: str = "per_page",
+    ):
+        self.finalize_and_validate_configuration()
+
+    @property
+    def base_url(self) -> str:
+        """
+        Construct the base URL for GitLab API requests.
+
+        Combines the configured GitLab host with the API version path (`/api/v4`).
+        The host URL is automatically trimmed of trailing slashes to ensure
+        proper URL construction.
+        """
+        return f"{self.gitlab_host.rstrip('/')}/api/v4"
+
+    def count_method(self, query: Query) -> str:
+        """
+        Return the HTTP method to use when requesting a record count.
+
+        GitLab supports HEAD requests for efficient counting without
+        returning the full response body.
+        """
+        return "HEAD"
+
+    def count(self, query: Query) -> CountQueryResult:
+        """
+        Return the count of records matching the query.
+
+        Makes a HEAD request to the GitLab API and extracts the total count
+        from the `x-total` response header. Returns a CountQueryResult object
+        as required by the clearskies backend interface.
+        """
+        self.check_query(query)
+        (url, method, body, headers) = self.build_records_request(query)
+        response = self.execute_request(url, self.count_method(query), json=body, headers=headers)
+        count = self._map_count_response(response.headers)
+        return CountQueryResult(count=count)
+
+    def _map_count_response(self, headers: CaseInsensitiveDict[str]) -> int:
+        """Extract the total record count from GitLab response headers."""
+        return int(headers.get("x-total", 0))
+
+    def conditions_to_request_parameters(
+        self, query: Query, used_routing_parameters: list[str]
+    ) -> tuple[str, dict[str, str], dict[str, Any]]:
+        """
+        Convert query conditions to GitLab API request parameters.
+
+        Transforms clearskies query conditions into URL parameters suitable for
+        the GitLab REST API. Only equality conditions are supported; other operators
+        will raise a ValueError.
+
+        If a condition targets the model's ID column, it will be URL-encoded and
+        returned as the route_id for path-based lookups.
+        """
+        route_id = ""
+
+        url_parameters = {}
+        for condition in query.conditions:
+            if condition.column_name in used_routing_parameters:
+                continue
+            if condition.operator != "=":
+                raise ValueError(
+                    f"I'm not very smart and only know how to search with the equals operator, but I received a condition of {condition.parsed}.  If you need to support this, you'll have to extend the ApiBackend and overwrite the build_records_request method."
+                )
+            if condition.column_name == query.model_class.id_column_name:
+                route_id = parse.quote_plus(condition.values[0]).replace("+", "%20")
+                continue
+            url_parameters[condition.column_name] = condition.values[0]
+
+        return (route_id, url_parameters, {})

clear_skies_gitlab-2.0.5/src/clearskies_gitlab/rest/gitlab_branch_rule.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from clearskies import Model
+from clearskies.columns import Boolean, Datetime, Integer, Json, String
+
+
+class GitlabBranchRule(Model):
+    """
+    Model representing a GitLab branch protection rule.
+
+    Branch rules in GitLab define protection settings for branches, controlling
+    who can push, merge, and unprotect branches. This model maps to the GitLab
+    REST API response for protected branches.
+
+    ```python
+    from clearskies_gitlab.rest import GitlabBranchRule
+    from clearskies_gitlab.rest.backends import GitlabRestBackend
+
+
+    class ProjectBranchRule(GitlabBranchRule):
+        backend = GitlabRestBackend()
+        table_name = "projects/{project_id}/protected_branches"
+
+
+    # Fetch all protected branches for a project
+    rules = ProjectBranchRule.where(project_id="my-project").all()
+    for rule in rules:
+        print(f"Branch: {rule.name}, Protected: {rule.protected}")
+    ```
+    """
+
+    """
+    The unique identifier for the branch rule.
+    """
+    id = Integer()
+
+    """
+    The name or pattern of the protected branch (e.g., `main`, `release/*`).
+    """
+    name = String()
+
+    """
+    Whether the branch is protected.
+    """
+    protected = Boolean()
+
+    """
+    Whether developers are allowed to push to the branch.
+    """
+    developers_can_push = Boolean()
+
+    """
+    Whether developers are allowed to merge into the branch.
+    """
+    developers_can_merge = Boolean()
+
+    """
+    Whether the current user can push to the branch.
+    """
+    can_push = Boolean()
+
+    """
+    Whether this is the default branch of the repository.
+    """
+    default = Boolean()
+
+    """
+    The timestamp when the branch rule was created.
+    """
+    created_at = Datetime()
+
+    """
+    The timestamp when the branch rule was last updated.
+    """
+    updated_at = Datetime()
+
+    """
+    Whether code owner approval is required for merges to this branch.
+    """
+    code_owner_approval_required = Boolean()
+
+    """
+    JSON array of access levels that can unprotect the branch.
+
+    Each entry contains information about who can remove protection from this branch.
+    """
+    unprotect_access_levels = Json()
+
+    """
+    JSON array of access levels that can push to the branch.
+
+    Each entry contains information about who can push directly to this branch.
+    """
+    push_access_levels = Json()

clear_skies_gitlab-2.0.5/src/clearskies_gitlab/rest/gitlab_cicd_variable.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from clearskies import Model
+from clearskies.columns import Boolean, String
+
+
+class GitlabCICDVariable(Model):
+    """
+    Model representing a GitLab CI/CD variable.
+
+    CI/CD variables in GitLab are used to store values that can be used in
+    CI/CD pipelines. They can be defined at the project, group, or instance level.
+    This model maps to the GitLab REST API response for CI/CD variables.
+
+    Note that the `key` field is used as the unique identifier (`id_column_name`)
+    since GitLab identifies variables by their key name.
+
+    ```python
+    from clearskies_gitlab.rest import GitlabCICDVariable
+    from clearskies_gitlab.rest.backends import GitlabRestBackend
+
+
+    class ProjectVariable(GitlabCICDVariable):
+        backend = GitlabRestBackend()
+        table_name = "projects/{project_id}/variables"
+
+
+    # Fetch all CI/CD variables for a project
+    variables = ProjectVariable.where(project_id="my-project").all()
+    for var in variables:
+        print(f"Key: {var.key}, Protected: {var.protected}")
+    ```
+    """
+
+    id_column_name = "key"
+
+    """
+    The name of the variable, used as the unique identifier.
+    """
+    key = String()
+
+    """
+    The value stored in the variable.
+
+    This may be masked in API responses if the `masked` flag is set.
+    """
+    value = String()
+
+    """
+    A human-readable description of the variable's purpose.
+    """
+    description = String()
+
+    """
+    The environment scope for the variable.
+
+    Determines which environments the variable is available in.
+    Use `*` for all environments or specify a specific environment name.
+    """
+    environment_scope = String()
+
+    """
+    The type of variable.
+
+    Can be `env_var` for environment variables or `file` for file-type variables.
+    """
+    variable_type = String()
+
+    """
+    Whether the variable value is masked in job logs.
+
+    When true, the variable value will be hidden in CI/CD job output.
+    """
+    masked = Boolean()
+
+    """
+    Whether the variable is only available in protected branches/tags.
+
+    When true, the variable is only exposed to pipelines running on
+    protected branches or tags.
+    """
+    protected = Boolean()
+
+    """
+    Whether the variable is hidden from the UI.
+
+    Hidden variables cannot be viewed or edited through the GitLab interface.
+    """
+    hidden = Boolean()
+
+    """
+    Whether the variable value should be treated as raw (no variable expansion).
+
+    When true, the variable value is used as-is without expanding any
+    embedded variable references.
+    """
+    raw = Boolean()

clear_skies_gitlab-2.0.5/src/clearskies_gitlab/rest/gitlab_member.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from clearskies import Model
+from clearskies.columns import Datetime, Email, Integer, Json, String
+
+
+class GitlabMember(Model):
+    """
+    Base model representing a GitLab group or project member.
+
+    Members in GitLab represent users who have been granted access to a group
+    or project with a specific access level. This model maps to the GitLab
+    REST API response for membership endpoints.
+
+    Access levels in GitLab are represented as integers:
+    - 10: Guest
+    - 20: Reporter
+    - 30: Developer
+    - 40: Maintainer
+    - 50: Owner
+
+    ```python
+    from clearskies_gitlab.rest import GitlabMember
+    from clearskies_gitlab.rest.backends import GitlabRestBackend
+
+
+    class ProjectMember(GitlabMember):
+        backend = GitlabRestBackend()
+        table_name = "projects/{project_id}/members"
+
+
+    # Fetch all members of a project
+    members = ProjectMember.where(project_id="my-project").all()
+    for member in members:
+        print(f"User: {member.username}, Access Level: {member.access_level}")
+    ```
+    """
+
+    id_column_name = "id"
+
+    """
+    The unique identifier for the member (user ID).
+    """
+    id = Integer()
+
+    """
+    The username of the member.
+    """
+    username = String()
+
+    """
+    The display name of the member.
+    """
+    name = String()
+
+    """
+    The current state of the user account.
+
+    Common values include `active`, `blocked`, or `deactivated`.
+    """
+    state = String()
+
+    """
+    URL to the member's avatar image.
+    """
+    avatar_url = String()
+
+    """
+    The access level granted to the member.
+
+    Integer values correspond to GitLab access levels:
+    10 (Guest), 20 (Reporter), 30 (Developer), 40 (Maintainer), 50 (Owner).
+    """
+    access_level = Integer()
+
+    """
+    The timestamp when the member was added.
+    """
+    created_at = Datetime()
+
+    """
+    JSON object containing information about who added this member.
+
+    Includes details like the user ID and username of the person who
+    granted membership.
+    """
+    created_by = Json()
+
+    """
+    The email address of the member.
+    """
+    email = Email()
+
+    """
+    JSON object containing SAML identity information for the member.
+
+    Only populated when SAML SSO is configured for the group.
+    Contains the extern_uid and provider information.
+    """
+    group_saml_identity = Json()