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

clearskies_gitlab/rest/models/gitlab_rest_project_approval_config.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from typing import Self
 
 from clearskies import Model
-from clearskies.columns import BelongsToId, BelongsToModel, Boolean
+from clearskies.columns import BelongsToId, BelongsToModel, Boolean, Integer
 
 from clearskies_gitlab.rest.backends import GitlabRestBackend
 from clearskies_gitlab.rest.models import gitlab_rest_project_reference
@@ -12,7 +12,32 @@ from clearskies_gitlab.rest.models import gitlab_rest_project_reference
 class GitlabRestProjectApprovalConfig(
     Model,
 ):
-    """Model for gitlab project protected branches."""
+    """
+    Model for GitLab project approval configuration.
+
+    This model provides access to the GitLab Merge Request Approvals API for
+    configuring project-level approval settings. These settings control how
+    merge request approvals work across the entire project.
+
+    See https://docs.gitlab.com/api/merge_request_approvals/#get-configuration for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectApprovalConfig
+
+
+    def my_function(approval_configs: GitlabRestProjectApprovalConfig):
+        # Get approval config for a specific project
+        config = approval_configs.find("project_id=123")
+        if config:
+            print(f"Reset approvals on push: {config.reset_approvals_on_push}")
+            print(f"Author can approve: {config.merge_requests_author_approval}")
+
+        # Update approval settings
+        config.save({"reset_approvals_on_push": True, "merge_requests_author_approval": False})
+    ```
+    """
 
     backend = GitlabRestBackend()
 
@@ -21,14 +46,77 @@ class GitlabRestProjectApprovalConfig(
         """Return the slug of the api endpoint for this model."""
         return "projects/:project_id/approvals"
 
+    """
+    The ID of the project this configuration belongs to.
+    """
     project_id = BelongsToId(gitlab_rest_project_reference.GitlabRestProjectReference)
+
+    """
+    The project model this configuration belongs to.
+    """
     project = BelongsToModel("project_id")
 
     id_column_name = "project_id"
 
+    """
+    Whether to reset approvals when new commits are pushed.
+
+    When enabled, any existing approvals are removed when new commits
+    are pushed to the merge request.
+    """
     reset_approvals_on_push = Boolean()
+
+    """
+    Whether users must enter their password to approve.
+
+    Adds an extra layer of security by requiring password confirmation.
+    """
     require_user_password_for_approval = Boolean()
+
+    """
+    Whether to prevent overriding approvers per merge request.
+
+    When enabled, the project-level approval rules cannot be modified
+    on individual merge requests.
+    """
     disable_overriding_approvers_per_merge_request = Boolean()
+
+    """
+    Whether merge request authors can approve their own requests.
+
+    When enabled, the author of a merge request can also approve it.
+    """
     merge_requests_author_approval = Boolean()
+
+    """
+    Whether committers are prevented from approving.
+
+    When enabled, users who have committed to the merge request
+    cannot approve it.
+    """
     merge_requests_disable_committers_approval = Boolean()
+
+    """
+    Whether reauthentication is required to approve.
+
+    When enabled, users must reauthenticate before they can approve
+    a merge request.
+    """
     require_reauthentication_to_approve = Boolean()
+
+    """
+    Whether to reset approvals from Code Owners if their files change.
+
+    When enabled, approvals from Code Owners are reset when files they
+    own are modified. Note: To use this field, reset_approvals_on_push
+    must be False.
+    """
+    selective_code_owner_removals = Boolean()
+
+    """
+    The number of required approvals before a merge request can merge.
+
+    Deprecated in GitLab 12.3. Use Approval Rules instead.
+    This field is still returned by the API for backwards compatibility.
+    """
+    approvals_before_merge = Integer()

clearskies_gitlab/rest/models/gitlab_rest_project_approval_rule.py

@@ -15,7 +15,34 @@ from clearskies_gitlab.rest.models import gitlab_rest_project_reference
 class GitlabRestProjectApprovalRule(
     Model,
 ):
-    """Model for gitlab project protected branches."""
+    """
+    Model for GitLab project approval rules.
+
+    This model provides access to the GitLab Merge Request Approval Rules API
+    for managing project-level approval rules. Approval rules define who must
+    approve merge requests and how many approvals are required.
+
+    See https://docs.gitlab.com/api/merge_request_approvals/#get-project-level-rules for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectApprovalRule
+
+
+    def my_function(approval_rules: GitlabRestProjectApprovalRule):
+        # List all approval rules for a project
+        for rule in approval_rules.where("project_id=123"):
+            print(f"Rule: {rule.name}")
+            print(f"Approvals required: {rule.approvals_required}")
+            print(f"Type: {rule.type}")
+
+        # Find a specific rule
+        code_owner_rule = approval_rules.find("project_id=123&type=code_owner")
+        if code_owner_rule:
+            print(f"Code owner approvers: {code_owner_rule.eligible_approvers}")
+    ```
+    """
 
     backend = GitlabRestBackend()
 
@@ -26,17 +53,81 @@ class GitlabRestProjectApprovalRule(
 
     id_column_name = "id"
 
+    """
+    The display name of the approval rule.
+    """
     name = String()
+
+    """
+    The unique identifier for the approval rule.
+    """
     id = Integer()
+
+    """
+    The type of approval rule.
+
+    Values:
+    - "regular": A standard approval rule
+    - "code_owner": Automatically created from CODEOWNERS file
+    - "report_approver": Created from security/compliance reports
+    """
     type = Select(allowed_values=["regular", "code_owner", "report_approver"])
+
+    """
+    The number of approvals required for this rule.
+    """
     approvals_required = Integer()
+
+    """
+    Whether this rule applies to all protected branches.
+
+    When true, the rule is enforced on all protected branches.
+    When false, it only applies to specific protected branches.
+    """
     applies_to_all_protected_branches = Boolean()
 
+    """
+    The ID of the project this rule belongs to.
+    """
     project_id = BelongsToId(gitlab_rest_project_reference.GitlabRestProjectReference)
+
+    """
+    The project model this rule belongs to.
+    """
     project = BelongsToModel("project_id")
 
+    """
+    List of users who can approve merge requests under this rule.
+
+    Contains user objects with id, name, username, etc.
+    """
     eligible_approvers = Json()
+
+    """
+    List of users assigned to this approval rule.
+
+    Contains user objects with id, name, username, etc.
+    """
     users = Json()
+
+    """
+    List of groups assigned to this approval rule.
+
+    Contains group objects with id, name, path, etc.
+    """
     groups = Json()
+
+    """
+    List of protected branches this rule applies to.
+
+    Only populated when applies_to_all_protected_branches is false.
+    Contains branch objects with id, name, etc.
+    """
     protected_branches = Json()
+
+    """
+    Whether this rule contains hidden groups.
+
+    Hidden groups are groups the current user doesn't have access to view.
+    """
     contains_hidden_groups = Boolean()

clearskies_gitlab/rest/models/gitlab_rest_project_member.py

@@ -11,7 +11,41 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 class GitlabRestProjectMember(
     gitlab_member.GitlabMember,
 ):
-    """Model for project members."""
+    """
+    Model for GitLab project members.
+
+    This model provides access to the GitLab Project Members API for managing
+    project membership. It extends the base GitlabMember class with project-specific
+    functionality.
+
+    See https://docs.gitlab.com/api/members/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectMember
+
+
+    def my_function(members: GitlabRestProjectMember):
+        # List all members of a project
+        for member in members.where("project_id=123"):
+            print(f"Member: {member.username}")
+            print(f"Access level: {member.access_level}")
+
+        # Search for specific members
+        for member in members.where("project_id=123&query=john"):
+            print(f"Found: {member.name}")
+
+        # Add a new member
+        members.create(
+            {
+                "project_id": 123,
+                "user_id": 456,
+                "access_level": 30,  # Developer
+            }
+        )
+    ```
+    """
 
     backend = GitlabRestBackend()
     id_column_name = "id"
@@ -21,9 +55,36 @@ class GitlabRestProjectMember(
         """Return the slug of the api endpoint for this model."""
         return "projects/:project_id/members"
 
+    """
+    The ID of the project to query members for.
+    """
     project_id = String()
+
+    """
+    Search query to filter members by name or username.
+    """
     query = String()
+
+    """
+    List of user IDs to filter results.
+    """
     user_ids = Json()
+
+    """
+    List of user IDs to exclude from results.
+    """
     skip_users = Json()
+
+    """
+    Whether to include seat information in the response.
+
+    Only available for groups with a paid plan.
+    """
     show_seat_info = Boolean()
+
+    """
+    Whether to include inherited members.
+
+    When true, includes members inherited from parent groups.
+    """
     all = Boolean()

clearskies_gitlab/rest/models/gitlab_rest_project_protected_branch.py

@@ -12,7 +12,33 @@ from clearskies_gitlab.rest.models import gitlab_rest_project_reference
 class GitlabRestProjectProtectedBranch(
     Model,
 ):
-    """Model for gitlab project protected branches."""
+    """
+    Model for GitLab project protected branches.
+
+    This model represents a protected branch in a GitLab project. Protected branches are used to
+    prevent unauthorized changes to important branches and enforce code review policies.
+
+    See https://docs.gitlab.com/api/protected_branches/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectProtectedBranch
+
+
+    def my_function(protected_branches: GitlabRestProjectProtectedBranch):
+        # List all protected branches for a project
+        for branch in protected_branches.where("project_id=123"):
+            print(f"Branch: {branch.name}, Force push allowed: {branch.allow_force_push}")
+
+        # Find a specific protected branch
+        main_branch = protected_branches.find("name=main")
+        if main_branch:
+            print(
+                f"Main branch requires code owner approval: {main_branch.code_owner_approval_required}"
+            )
+    ```
+    """
 
     @classmethod
     def destination_name(cls: type[Self]) -> str:
@@ -23,13 +49,118 @@ class GitlabRestProjectProtectedBranch(
 
     backend = GitlabRestBackend()
 
+    """
+    The ID of the protected branch.
+    """
     id = Integer()
+
+    """
+    The name of the protected branch or wildcard pattern.
+
+    Can be an exact branch name (e.g., "main") or a wildcard pattern (e.g., "release/*").
+    """
     name = String()
+
+    """
+    Whether force push is allowed on this protected branch.
+
+    If `True`, users with push access can force push to this branch.
+    """
     allow_force_push = Boolean()
+
+    """
+    Whether code owner approval is required for pushes to this branch.
+
+    If `True`, code owners must approve changes before they can be merged.
+    This feature is available in GitLab Premium and Ultimate.
+    """
     code_owner_approval_required = Boolean()
+
+    """
+    Whether the protection settings are inherited from the parent group.
+
+    If `True`, the protection settings were inherited from the project's parent group.
+    This field is only available in GitLab Premium and Ultimate.
+    """
+    inherited = Boolean()
+
+    """
+    Array of merge access level configurations.
+
+    Each entry in the array contains:
+    - `id`: ID of the merge access level configuration
+    - `access_level`: Access level for merging (e.g., 40 for Maintainers)
+    - `access_level_description`: Human-readable description of the access level
+    - `user_id`: ID of the user with merge access (Premium and Ultimate only)
+    - `group_id`: ID of the group with merge access (Premium and Ultimate only)
+
+    Example:
+    ```json
+    [
+        {
+            "id": 2001,
+            "access_level": 40,
+            "access_level_description": "Maintainers"
+        }
+    ]
+    ```
+    """
     merge_access_levels = Json()
+
+    """
+    Array of push access level configurations.
+
+    Each entry in the array contains:
+    - `id`: ID of the push access level configuration
+    - `access_level`: Access level for pushing (e.g., 40 for Maintainers)
+    - `access_level_description`: Human-readable description of the access level
+    - `user_id`: ID of the user with push access (Premium and Ultimate only)
+    - `group_id`: ID of the group with push access (Premium and Ultimate only)
+    - `deploy_key_id`: ID of the deploy key with push access
+
+    Example:
+    ```json
+    [
+        {
+            "id": 1001,
+            "access_level": 40,
+            "access_level_description": "Maintainers"
+        },
+        {
+            "id": 1002,
+            "access_level": 40,
+            "access_level_description": "Deploy key",
+            "deploy_key_id": 1
+        }
+    ]
+    ```
+    """
     push_access_levels = Json()
+
+    """
+    Array of unprotect access level configurations.
+
+    Each entry in the array contains:
+    - `id`: ID of the unprotect access level configuration
+    - `access_level`: Access level for unprotecting (e.g., 40 for Maintainers)
+    - `access_level_description`: Human-readable description of the access level
+    - `user_id`: ID of the user with unprotect access (Premium and Ultimate only)
+    - `group_id`: ID of the group with unprotect access (Premium and Ultimate only)
+
+    This defines who can unprotect the branch.
+    """
     unprotect_access_levels = Json()
 
+    """
+    The ID of the project this protected branch belongs to.
+
+    This is used to scope the API requests to a specific project.
+    """
     project_id = BelongsToId(gitlab_rest_project_reference.GitlabRestProjectReference)
+
+    """
+    The project model this protected branch belongs to.
+
+    Provides access to the full project object via the relationship.
+    """
     project = BelongsToModel("project_id")

clearskies_gitlab/rest/models/gitlab_rest_project_repository_commit.py

@@ -12,7 +12,40 @@ from clearskies_gitlab.rest.models import gitlab_rest_project_repository_commit_
 class GitlabRestProjectRepositoryCommit(
     Model,
 ):
-    """Model for projects repository commits."""
+    """
+    Model for GitLab project repository commits.
+
+    This model provides access to the GitLab Commits API for retrieving
+    commit information from a project's repository. Commits represent
+    individual changes to the repository.
+
+    See https://docs.gitlab.com/api/commits/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectRepositoryCommit
+
+
+    def my_function(commits: GitlabRestProjectRepositoryCommit):
+        # List commits for a project
+        for commit in commits.where("project_id=123"):
+            print(f"Commit: {commit.short_id}")
+            print(f"Author: {commit.author_name}")
+            print(f"Title: {commit.title}")
+
+        # Get commits for a specific branch
+        for commit in commits.where("project_id=123&ref_name=main"):
+            print(f"{commit.short_id}: {commit.title}")
+
+        # Get commits with stats
+        for commit in commits.where("project_id=123&with_stats=true"):
+            print(f"Commit: {commit.short_id}")
+            # Access the diff
+            if commit.diff:
+                print(f"Diff: {commit.diff.diff}")
+    ```
+    """
 
     backend = GitlabRestBackend()
     id_column_name = "id"
@@ -22,33 +55,142 @@ class GitlabRestProjectRepositoryCommit(
         """Return the slug of the api endpoint for this model."""
         return "projects/:project_id/repository/commits"
 
+    """
+    The diff associated with this commit.
+
+    Provides access to the file changes in this commit.
+    """
     diff = HasOne(
         gitlab_rest_project_repository_commit_diff.GitlabRestProjectRepositoryCommitDiff,
         foreign_column_name="commit_id",
         where=lambda model, parent: model.where(f"gitlab_project_id={parent.id}"),
     )
 
+    """
+    The full commit SHA hash.
+
+    This is the unique identifier for the commit.
+    """
     id = String()
+
+    """
+    The shortened commit SHA hash.
+
+    Typically the first 8 characters of the full SHA.
+    """
     short_id = String()
+
+    """
+    The commit title (first line of the commit message).
+    """
     title = String()
+
+    """
+    The name of the commit author.
+    """
     author_name = String()
+
+    """
+    The email address of the commit author.
+    """
     author_email = Email()
+
+    """
+    The date and time when the commit was authored.
+    """
     authored_date = Datetime()
+
+    """
+    The name of the committer.
+
+    May differ from author if the commit was applied by someone else.
+    """
     committer_name = String()
+
+    """
+    The email address of the committer.
+    """
     committer_email = Email()
+
+    """
+    The date and time when the commit was committed.
+    """
     committed_date = Datetime()
+
+    """
+    The date and time when the commit was created in GitLab.
+    """
     created_at = Datetime()
+
+    """
+    The full commit message.
+    """
     messsage = String()
+
+    """
+    List of parent commit SHA hashes.
+
+    Most commits have one parent. Merge commits have two.
+    """
     parent_ids = Json()
+
+    """
+    URL to view the commit in GitLab.
+    """
     web_url = String()
+
+    """
+    Extended trailer information from the commit message.
+
+    Git trailers are key-value pairs at the end of commit messages.
+    """
     extended_trailers = Json()
-    # search params
+
+    ### Search params
+
+    """
+    The ID of the project to query commits for.
+    """
     project_id = Integer()
+
+    """
+    The branch, tag, or commit SHA to list commits from.
+    """
     ref_name = String()
+
+    """
+    Filter commits after this date.
+    """
     since = Datetime()
+
+    """
+    Filter commits before this date.
+    """
     until = Datetime()
+
+    """
+    Filter commits affecting this file path.
+    """
     path = String()
+
+    """
+    Whether to retrieve commits from all branches.
+    """
     all = Boolean()
+
+    """
+    Whether to include commit statistics (additions, deletions).
+    """
     with_stats = Boolean()
+
+    """
+    Whether to follow only the first parent on merge commits.
+
+    Useful for getting a linear history.
+    """
     first_parent = Boolean()
+
+    """
+    Whether to include Git trailers in the response.
+    """
     trailers = Boolean()