clear-skies-gitlab 2.0.4__py3-none-any.whl → 2.0.5__py3-none-any.whl

{clear_skies_gitlab-2.0.4.dist-info → clear_skies_gitlab-2.0.5.dist-info}/METADATA

@@ -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.dist-info → clear_skies_gitlab-2.0.5.dist-info}/RECORD

@@ -1,7 +1,7 @@
 clearskies_gitlab/__init__.py,sha256=TlKrAfFOTW6YnQefxEQbUdnf_F3sVOvRKsG_6cfFAsk,123
 clearskies_gitlab/defaults/__init__.py,sha256=t3Dfm98aoahHCepQnW1YBSVKgDz0QEp7hTrGL8XAcTE,341
-clearskies_gitlab/defaults/gitlab_default_auth.py,sha256=w8w7LcekC38tbD-fuv5liDnvo4UsBxKVF7YZoTuzUus,456
-clearskies_gitlab/defaults/gitlab_default_host.py,sha256=wlyj0u-nbUqkkZQnZFgMXKH32nNlTABfCL6iWA88V6E,411
+clearskies_gitlab/defaults/gitlab_default_auth.py,sha256=zSa8R0hgIYgj5DX_wPF7FyDqYjbAitepOoYC1_wCeqA,1566
+clearskies_gitlab/defaults/gitlab_default_host.py,sha256=gi2qiZ5k28ER-TRpA7GYO4hPILUJxM0bFbxTIEas2V4,1326
 clearskies_gitlab/defaults/gitlab_graphql_client.py,sha256=eIQ3efp2oYFuGSIGimZ1e5AC8TOTy1j8K26SU_AK-yU,609
 clearskies_gitlab/exceptions/__init__.py,sha256=QUg8lVn91QMENpN_uZmYdNkhI1EjFAWN9X6cMKgKmtE,301
 clearskies_gitlab/exceptions/gitlab_error.py,sha256=5hm8iYXnEfxxRkKPBXIq0v5mL1l5ZqaxlmUKnBjOe3g,2054
@@ -18,51 +18,51 @@ clearskies_gitlab/graphql/models/gitlab_group_reference.py,sha256=V3y3DxKMhUWWjX
 clearskies_gitlab/graphql/models/gitlab_project.py,sha256=IBG38Rwks6A9aqC2Qlss_qWohNQ2oUHF64irwE3-mj8,641
 clearskies_gitlab/graphql/models/gitlab_project_reference.py,sha256=Z5Hi991TFQip-1151XcP-_ITVHwWmJiTDTlqRoAsg0A,290
 clearskies_gitlab/rest/__init__.py,sha256=KZyBO-7OCE_qgClt-eTOh8jYIJccKpcuXHZ4eZCpW-0,316
-clearskies_gitlab/rest/gitlab_branch_rule.py,sha256=D8HptQg9BdKAtPtVkRYbt1sga0R9eErECYDLLuvSa7A,569
-clearskies_gitlab/rest/gitlab_cicd_variable.py,sha256=398-5SPlMk3-Zyu1dZTbpM9YCP2qNOsnydku3hiWvlc,446
-clearskies_gitlab/rest/gitlab_member.py,sha256=o1G652wbIImd8rz9NJQeAlJaxAftNt-6u7quoLYFwh0,487
+clearskies_gitlab/rest/gitlab_branch_rule.py,sha256=9YqoudklWKUk3x51xPBJvabZCS4_KoOxGDTc3oyXLik,2376
+clearskies_gitlab/rest/gitlab_cicd_variable.py,sha256=txuJM3GVcMcH06y7D33y4msYMWYTVE1GVitPuQNW--g,2608
+clearskies_gitlab/rest/gitlab_member.py,sha256=-x5t5ZArHRZ_XgAvNRKPfdsGd2WYZpMfezh2mfO3fJc,2391
 clearskies_gitlab/rest/backends/__init__.py,sha256=xUhpRXyB_FHhTsz94A2kviBlPzZfaKqIiHOhDrNg6Wc,115
-clearskies_gitlab/rest/backends/gitlab_rest_backend.py,sha256=nAZe8JRD1xMUNNoinOBWAGWv__S3Jko9d7OhXUlTeQk,6672
+clearskies_gitlab/rest/backends/gitlab_rest_backend.py,sha256=OpAYhLkoNmggM-6OZONjmV8BCV6r2wPlATMb2TxF_BQ,6345
 clearskies_gitlab/rest/models/__init__.py,sha256=mcfdh04R8Fu5T-6Cz-Iy3CJ2LLttgkwBGd3Qp0Rtt6A,2750
-clearskies_gitlab/rest/models/gitlab_rest_advanced_search.py,sha256=iFxCGDaqzRxl2a9g91P7zpj2ZAxuRbYoSiz_hsXMavY,883
-clearskies_gitlab/rest/models/gitlab_rest_advanced_search_blob.py,sha256=R3DFxbAcm3Em8S6dZ51EG6m-OSaM-BQmuo035SHV5NU,628
-clearskies_gitlab/rest/models/gitlab_rest_current_user.py,sha256=KrOfehkusr_FlB8Q4-IOU51Go5ULgykBDi9v883w80k,1135
-clearskies_gitlab/rest/models/gitlab_rest_group.py,sha256=iJgz78APzdlK9TOv0OmqVU_3qg-lJ3cdUBkMjyqhYho,1410
-clearskies_gitlab/rest/models/gitlab_rest_group_access_token.py,sha256=83tvO01CQktMwLm1Is9fIf_IkGR6zFIvvELwjkdSr4s,843
+clearskies_gitlab/rest/models/gitlab_rest_advanced_search.py,sha256=NQYX9AH-MwT77oFvTrubZmaar7okN0HQU-fCQ6iQtjE,2964
+clearskies_gitlab/rest/models/gitlab_rest_advanced_search_blob.py,sha256=jESJma3csPfrgV3KdlBZqtxIiZAd5MEKsdu7XNwBzbw,2472
+clearskies_gitlab/rest/models/gitlab_rest_current_user.py,sha256=jR9z16rYilkmngGJnAs1ABODMd8corYHLW3V3S0buH0,3917
+clearskies_gitlab/rest/models/gitlab_rest_group.py,sha256=9tNj5RRMXh05wG1XVlh8TTCStSgfuZ7eWYchTfyZp40,2907
+clearskies_gitlab/rest/models/gitlab_rest_group_access_token.py,sha256=j_iByq4lKZ9sAhVTCBrNPf6ThtDanC8Y4cpA_F4iLtA,3294
 clearskies_gitlab/rest/models/gitlab_rest_group_access_token_reference.py,sha256=GZnAOIgIDJCPR55ABD4bxPT--TUOnkVV1peQMtai2dU,358
-clearskies_gitlab/rest/models/gitlab_rest_group_base.py,sha256=lnX37uxnIu1aWmGjDuT1ZVk9NeHQwmnFRjS_2Wjq53s,3102
-clearskies_gitlab/rest/models/gitlab_rest_group_member.py,sha256=CLkslCom4Deo2c3GdkoM8cuVYLOsvfreYzOUm64DTNs,707
+clearskies_gitlab/rest/models/gitlab_rest_group_base.py,sha256=GON6nD600ZkenpMh4Y_sS5rXwo5l2vzMwiXtoIdn5hs,8435
+clearskies_gitlab/rest/models/gitlab_rest_group_member.py,sha256=TkUIhH_4Cd9TrFjNVi657TMY1FjExPIM1ueXpKVaVNs,2323
 clearskies_gitlab/rest/models/gitlab_rest_group_member_reference.py,sha256=XrhG_hiqGQf8vIosss2Vp4RWvNNtHxIn-TzXtPGQvgU,331
-clearskies_gitlab/rest/models/gitlab_rest_group_project.py,sha256=33hEMN08aIsl4-tcIgNmruGLRYr0XqIuD9nQZ3Xs_CY,415
+clearskies_gitlab/rest/models/gitlab_rest_group_project.py,sha256=bvUy7kRgWPaZocbxKcuqpfBxFdyxmDeOb02_klQiPVU,1281
 clearskies_gitlab/rest/models/gitlab_rest_group_project_reference.py,sha256=fp45VWXMC_3inaep1GIS6ortIucZoxh-7xb7RnTl8DI,336
 clearskies_gitlab/rest/models/gitlab_rest_group_reference.py,sha256=UiHQpQNuVM3WotCNEFIlEqLwXMdy-8YqYRil-S84MQI,292
-clearskies_gitlab/rest/models/gitlab_rest_group_search.py,sha256=VgpGDRwe3UhY2AXfqWpGYYY6ghUhoDNKJqeLsrNtwcA,506
-clearskies_gitlab/rest/models/gitlab_rest_group_search_blob.py,sha256=_tIkwwDzJF9nGV0LL9fVqY5Tn4SSBXNg1C0dKlUQ-oM,353
-clearskies_gitlab/rest/models/gitlab_rest_group_subgroup.py,sha256=x0h_alIV3QFbslXIlqHC48HAOmmFw5T96XAwWh31-uA,1937
+clearskies_gitlab/rest/models/gitlab_rest_group_search.py,sha256=csQAVv93Y37oVk__agqEsC1mmbu0h68hpWG34VYJS0s,1466
+clearskies_gitlab/rest/models/gitlab_rest_group_search_blob.py,sha256=kecmETgb-5EnekJDVfRHgIARvFQ46oSGTRZP1PPA7XI,1251
+clearskies_gitlab/rest/models/gitlab_rest_group_subgroup.py,sha256=EGLEaOIzU3QpqOVk1SG9Npsx49mTVXIVr4Q_S6zzdLo,2727
 clearskies_gitlab/rest/models/gitlab_rest_group_subgroup_reference.py,sha256=vFAlOmQ8wJswlcNGJ9zrrxidsFXC70hDfYNrNZ5VQ9g,341
-clearskies_gitlab/rest/models/gitlab_rest_group_variable.py,sha256=ixs4o6BV31sepagW46d4ipunn-szKNCHtlqKB6IxG5o,607
+clearskies_gitlab/rest/models/gitlab_rest_group_variable.py,sha256=20vldlXL69Y52CT3ylxDBM429ga9sqmZvqdB1uGzM2w,1932
 clearskies_gitlab/rest/models/gitlab_rest_group_variable_reference.py,sha256=rGgqrOY-HCxpsstDb1_Hy_KwPt6Z37xxIJnBRD9eXXw,341
-clearskies_gitlab/rest/models/gitlab_rest_namespace.py,sha256=AIh56mDeB8LtrKVhWEtZ1Gop_V9enBdObjpKfK5b-0g,2484
-clearskies_gitlab/rest/models/gitlab_rest_project.py,sha256=Nc6u-R3Pb4NO6pZUYtZ6RYkygqizyiTybIkpFN47aXM,6687
-clearskies_gitlab/rest/models/gitlab_rest_project_approval_config.py,sha256=E1Yhk4kWQfWA1Peyml0yrJuJeqkFfMvYffQ7vmfNmoc,1099
+clearskies_gitlab/rest/models/gitlab_rest_namespace.py,sha256=nTqDb2CDFAa1SBFnGZxw-s4M8DJZS7yqyPI16poY0Ew,5610
+clearskies_gitlab/rest/models/gitlab_rest_project.py,sha256=PcI08WIkv9c4H-b0d8qsxfYMKLGSAT8Ms9mbul0g9IQ,15019
+clearskies_gitlab/rest/models/gitlab_rest_project_approval_config.py,sha256=W3rsRx6YSlpcy6k5vZ-cvNW36rtZ15pcI150vgGkB-c,3172
 clearskies_gitlab/rest/models/gitlab_rest_project_approval_config_reference.py,sha256=Gfs1iFo8VOH8llpcdOquZ7uNA5qFv6LNaGx-glTC3AM,383
-clearskies_gitlab/rest/models/gitlab_rest_project_approval_rule.py,sha256=W1bHWl1kv9Avs3oBtOAowVpVB0-pe2mXGDFyQuxUnJM,1249
+clearskies_gitlab/rest/models/gitlab_rest_project_approval_rule.py,sha256=Cc5rk6KbBhibtIgUVQ7LT9WBrIXI3AepFcYsdmvzw00,3710
 clearskies_gitlab/rest/models/gitlab_rest_project_approval_rule_reference.py,sha256=VTWBcv225UQyxFr8ZdTpgEdXCiTerYGIbYyGdt1j-tc,373
-clearskies_gitlab/rest/models/gitlab_rest_project_member.py,sha256=StXXvQ4Hs5VV2ngEMGvhdKwbXwlOu1ABbeQ-rfM3r48,717
+clearskies_gitlab/rest/models/gitlab_rest_project_member.py,sha256=QtcjOu799gKcfVUi9XJqEXQi2CrSZFxB_TBmbtbl6GM,2208
 clearskies_gitlab/rest/models/gitlab_rest_project_member_reference.py,sha256=nNz0Qm5Q5Esyugk9IiNe3Y2Q9SNwWPiLxpOQuiMNAMk,341
-clearskies_gitlab/rest/models/gitlab_rest_project_protected_branch.py,sha256=95peeiCkBQCCsYWidIWWNAywBnPh1w9NUzVtrOIQwHY,1031
+clearskies_gitlab/rest/models/gitlab_rest_project_protected_branch.py,sha256=8rn3MRHefmB9XCLornF-uQ5PcWWlZrGaEYWgt07Quso,5177
 clearskies_gitlab/rest/models/gitlab_rest_project_protected_branch_reference.py,sha256=TCP892aJDxn_YKR0wJFfOTfkwOHoDAc6uBvrDYO5fl8,388
 clearskies_gitlab/rest/models/gitlab_rest_project_reference.py,sha256=Rg3-fjN9WHoIsubKO3Un1trqPU1-ZoZAkE6jW33P568,302
-clearskies_gitlab/rest/models/gitlab_rest_project_repository_commit.py,sha256=h9Q3b3YtFXpCC_OVqckohm1tCZwGCfojBL3qo6I3oSw,1532
-clearskies_gitlab/rest/models/gitlab_rest_project_repository_commit_diff.py,sha256=xUxnA6TGOfwSraojid06V1wXOF-Tqp8JXw0a7Kg50nc,894
-clearskies_gitlab/rest/models/gitlab_rest_project_repository_contributor.py,sha256=QEvGxMOHIKFPoxjo9OzESaJ_syHij9o_dubFvhacIJo,971
+clearskies_gitlab/rest/models/gitlab_rest_project_repository_commit.py,sha256=qGTeQHpj0_HbHZ6XnMtRcHSeuCW2BoYIpSNiLuCRlEc,4564
+clearskies_gitlab/rest/models/gitlab_rest_project_repository_commit_diff.py,sha256=ICrM-UuVuygVG7VfbPhjBBy1XwSaL7_J5Cydin8S0Wg,2967
+clearskies_gitlab/rest/models/gitlab_rest_project_repository_contributor.py,sha256=CaEsOuajhAblbxnSzVFgiWA8sVSB8-lZkYCCIbNkcKk,2808
 clearskies_gitlab/rest/models/gitlab_rest_project_repository_contributor_reference.py,sha256=yEIO424xhYcN7YpyAVXseMVET48RZ0hpu_WOOZTf3LA,418
-clearskies_gitlab/rest/models/gitlab_rest_project_repository_file.py,sha256=0yYNi2zgUjl4UAjUvDaJ92wIutxOEpzBKNE-7dBN3ZQ,1112
-clearskies_gitlab/rest/models/gitlab_rest_project_repository_file_raw.py,sha256=oExYzvAT6mUxY5mkw-nkAUZh-MmWy5lXq9UcFRst7nA,895
+clearskies_gitlab/rest/models/gitlab_rest_project_repository_file.py,sha256=ZhSsSh7GFgwVarKEHUU1yAEuiBW3rVf45vWqwNJh7bg,3220
+clearskies_gitlab/rest/models/gitlab_rest_project_repository_file_raw.py,sha256=XL4b3EexuzcEXcsP1sDu74Nxpjlpb7jM71tM_OymxwI,2464
 clearskies_gitlab/rest/models/gitlab_rest_project_repository_file_reference.py,sha256=WiK7aOhBZD_8HRvvlTQ6oWk3hXOJAyfEKdqmCIUIM9M,383
-clearskies_gitlab/rest/models/gitlab_rest_project_variable.py,sha256=rfmk38ndgtdzoaoUFxRDPLhrRc5JWuNa2B2mWO1q4aM,813
+clearskies_gitlab/rest/models/gitlab_rest_project_variable.py,sha256=D8FjgGafJOUQhM62hSWgYbNDABrF4mBNigY8lWBH7f4,2097
 clearskies_gitlab/rest/models/gitlab_rest_project_variable_reference.py,sha256=6P-9TbvhYMZGoBMM-BFFDFKsN40LEXd9FKYNTFpNayU,351
-clear_skies_gitlab-2.0.4.dist-info/METADATA,sha256=Qub88NvHlz3Yj4cmBZ-AZnGlWg_9O7ZDKCl_yhbnJfA,2143
-clear_skies_gitlab-2.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-clear_skies_gitlab-2.0.4.dist-info/licenses/LICENSE,sha256=S7gzTni6Tje0gBaQnXxs5BXdrBBKQ9eAVWjMHZccST8,1069
-clear_skies_gitlab-2.0.4.dist-info/RECORD,,
+clear_skies_gitlab-2.0.5.dist-info/METADATA,sha256=9p7QHC--LHWZChCcTMEJWP7qcb0TrNZ8k43a07Aq_iw,2143
+clear_skies_gitlab-2.0.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clear_skies_gitlab-2.0.5.dist-info/licenses/LICENSE,sha256=S7gzTni6Tje0gBaQnXxs5BXdrBBKQ9eAVWjMHZccST8,1069
+clear_skies_gitlab-2.0.5.dist-info/RECORD,,

clearskies_gitlab/defaults/gitlab_default_auth.py

@@ -2,9 +2,40 @@ import clearskies
 
 
 class GitlabDefaultAuth(clearskies.di.AdditionalConfigAutoImport):
-    """Provide default Gitlab authentication from environment."""
+    """
+    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 from 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 ")

clearskies_gitlab/defaults/gitlab_default_host.py

@@ -2,9 +2,38 @@ import clearskies
 
 
 class GitlabDefaultHost(clearskies.di.AdditionalConfigAutoImport):
-    """Provide default GitLab Host from environment."""
+    """
+    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 from environment or default."""
+        """
+        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/"

clearskies_gitlab/rest/backends/gitlab_rest_backend.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
-import urllib
 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:
@@ -16,14 +17,77 @@ if TYPE_CHECKING:
 
 
 class GitlabRestBackend(ApiBackend):
-    """Backend for Gitlab.com."""
+    """
+    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
@@ -43,58 +107,54 @@ class GitlabRestBackend(ApiBackend):
     @property
     def base_url(self) -> str:
         """
-        Docstring for base_url.
+        Construct the base URL for GitLab API requests.
 
-        :param self: Description
-        :return: Description
-        :rtype: str
+        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 request method to use when making a request for a record count."""
+        """
+        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) -> int:
-        """Return the count of records matching the query."""
+    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)
-        return self._map_count_response(response.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 map_records_response(
-    #     self, response_data: Any, query: Query, query_data: dict[str, Any] | None = None
-    # ) -> list[dict[str, Any]]:
-    #     """Map the response data to model records with support for nested fields."""
-    #     if query_data is None:
-    #         query_data = {}
-
-    #     columns = query.model_class.get_columns()
-    #     result = []
-
-    #     # Handle list response
-    #     if isinstance(response_data, list):
-    #         for item in response_data:
-    #             if not isinstance(item, dict):
-    #                 continue
-    #             mapped = self.check_dict_and_map_to_model(item, columns, query_data)
-    #             if mapped:
-    #                 result.append(mapped)
-    #     # Handle single object response
-    #     elif isinstance(response_data, dict):
-    #         mapped = self.check_dict_and_map_to_model(response_data, columns, query_data)
-    #         if mapped:
-    #             result.append(mapped)
-
-    #     return result
-
     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 request parameters."""
+        """
+        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 = {}
@@ -106,50 +166,8 @@ class GitlabRestBackend(ApiBackend):
                     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 = urllib.parse.quote_plus(condition.values[0]).replace("+", "%20")
+                route_id = parse.quote_plus(condition.values[0]).replace("+", "%20")
                 continue
             url_parameters[condition.column_name] = condition.values[0]
 
         return (route_id, url_parameters, {})
-
-    # def set_next_page_data_from_response(
-    #     self,
-    #     next_page_data: dict[str, Any],
-    #     query: Query,
-    #     response: requests.Response,
-    # ) -> None:
-    #     """
-    #     Update the next_page_data dictionary with the appropriate data needed to fetch the next page of records.
-
-    #     This method has a very important job, which is to inform clearskies about how to make another API call to fetch the next
-    #     page of records.  The way this happens is by updating the `next_page_data` dictionary in place with whatever pagination
-    #     information is necessary.  Note that this relies on next_page_data being passed by reference, hence the need to update
-    #     it in place.  That means that you can do this:
-
-    #     ```python
-    #     next_page_data["some_key"] = "some_value"
-    #     ```
-
-    #     but if you do this:
-
-    #     ```python
-    #     next_page_data = {"some_key": "some_value"}
-    #     ```
-
-    #     Then things simply won't work.
-    #     """
-    #     # Different APIs generally have completely different ways of communicating pagination data, but one somewhat common
-    #     # approach is to use a link header, so let's support that in the base class.
-    #     if "link" not in response.headers:
-    #         return
-    #     next_link = [rel for rel in response.headers["link"].split(",") if 'rel="next"' in rel]
-    #     if not next_link:
-    #         return
-    #     parsed_next_link = urllib.parse.urlparse(next_link[0].split(";")[0].strip(" <>"))
-    #     query_parameters = urllib.parse.parse_qs(parsed_next_link.query)
-    #     if self.pagination_parameter_name not in query_parameters:
-    #         raise ValueError(
-    #             f"Configuration error with {self.__class__.__name__}!  I am configured to expect a pagination key of '{self.pagination_parameter_name}.  However, when I was parsing the next link from a response to get the next pagination details, I could not find the designated pagination key.  This likely means that backend.pagination_parameter_name is set to the wrong value.  The link in question was "
-    #             + parsed_next_link.geturl()
-    #         )
-    #     next_page_data[self.pagination_parameter_name] = query_parameters[self.pagination_parameter_name][0]

clearskies_gitlab/rest/gitlab_branch_rule.py

@@ -5,17 +5,90 @@ from clearskies.columns import Boolean, Datetime, Integer, Json, String
 
 
 class GitlabBranchRule(Model):
-    """Model for GitLab branch rules."""
+    """
+    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()

clearskies_gitlab/rest/gitlab_cicd_variable.py

@@ -5,16 +5,93 @@ from clearskies.columns import Boolean, String
 
 
 class GitlabCICDVariable(Model):
-    """Base model for groups ci/cd variables."""
+    """
+    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()