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

clearskies_gitlab/rest/models/gitlab_rest_group_base.py

@@ -20,7 +20,18 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 class GitlabRestGroupBase(
     Model,
 ):
-    """Model for groups."""
+    """
+    Base model for GitLab groups.
+
+    This model provides the common fields and functionality shared by all group-related
+    models (GitlabRestGroup, GitlabRestGroupSubgroup, etc.). It contains the core
+    group attributes and search parameters.
+
+    See https://docs.gitlab.com/api/groups/ for more details.
+
+    Note: This is a base class and should typically not be used directly.
+    Use GitlabRestGroup or GitlabRestGroupSubgroup instead.
+    """
 
     @classmethod
     def destination_name(cls: type[Self]) -> str:
@@ -31,74 +42,367 @@ class GitlabRestGroupBase(
 
     backend = GitlabRestBackend()
 
+    """
+    The unique identifier for the group.
+    """
     id = String()
+
+    """
+    URL to the group's GitLab page.
+    """
     web_url = String()
+
+    """
+    The display name of the group.
+    """
     name = String()
+
+    """
+    The URL-friendly path/slug of the group.
+    """
     path = String()
+
+    """
+    A description of the group's purpose.
+    """
     description = String()
+
+    """
+    The visibility level of the group.
+
+    Values: "public", "internal", or "private".
+    """
     visibility = String()
+
+    """
+    Whether sharing the group with other groups is locked.
+    """
     share_with_group_lock = Boolean()
+
+    """
+    Whether two-factor authentication is required for group members.
+    """
     require_two_factor_authentication = Boolean()
+
+    """
+    Grace period (in hours) for enabling two-factor authentication.
+    """
     two_factor_grace_period = Integer()
+
+    """
+    Who can create projects in this group.
+
+    Values: "noone", "maintainer", "developer".
+    """
     project_creation_level = String()
+
+    """
+    Whether Auto DevOps is enabled for projects in this group.
+    """
     auto_devops_enabled = Boolean()
+
+    """
+    Who can create subgroups in this group.
+
+    Values: "owner", "maintainer".
+    """
     subgroup_creation_level = String()
+
+    """
+    Whether email notifications are disabled for this group.
+    """
     emails_disabled = Boolean()
+
+    """
+    Whether email notifications are enabled for this group.
+    """
     emails_enabled = Boolean()
+
+    """
+    Whether mentions are disabled for this group.
+    """
     mentions_disabled = String()
+
+    """
+    Whether Git LFS is enabled for projects in this group.
+    """
     lfs_enabled = String()
+
+    """
+    Whether math rendering limits are enabled.
+    """
     math_rendering_limits_enabled = Boolean()
+
+    """
+    Whether math rendering limits are locked.
+    """
     lock_math_rendering_limits_enabled = Boolean()
+
+    """
+    The default branch for new projects in this group.
+    """
     default_branch = String()
+
+    """
+    The default branch protection level.
+    """
     default_branch_protection = String()
+
+    """
+    Default branch protection settings.
+    """
     default_branch_protection_defaults = String()
+
+    """
+    URL to the group's avatar image.
+    """
     avatar_url = String()
+
+    """
+    Whether users can request access to this group.
+    """
     request_access_enabled = Boolean()
+
+    """
+    The full display name including parent groups.
+
+    For example: "Parent Group / Child Group".
+    """
     full_name = String()
+
+    """
+    The full path including parent groups.
+
+    For example: "parent-group/child-group".
+    """
     full_path = String()
+
+    """
+    The date and time when the group was created.
+    """
     created_at = Datetime()
+
+    """
+    The ID of the parent group.
+
+    Null for top-level groups.
+    """
     parent_id = String()
+
+    """
+    The ID of the organization this group belongs to.
+    """
     organization_id = String()
+
+    """
+    The shared runners setting for this group.
+
+    Controls whether shared runners are available to projects.
+    """
     shared_runners_setting = String()
+
+    """
+    Custom attributes attached to this group.
+    """
     custom_attributes = Json()
+
+    """
+    Statistics about the group (storage, repository size, etc.).
+    """
     statistics = Json()
+
+    """
+    LDAP Common Name for LDAP-synced groups.
+    """
     ldap_cn = String()
+
+    """
+    LDAP access level for LDAP-synced groups.
+    """
     ldap_access = String()
+
+    """
+    LDAP group links configuration.
+    """
     ldap_group_links = Json()
+
+    """
+    SAML group links configuration.
+    """
     saml_group_links = Json()
+
+    """
+    The ID of the project used for file templates.
+    """
     file_template_project_id = String()
+
+    """
+    The date when the group was marked for deletion.
+    """
     marked_for_deletion_on = Datetime()
+
+    """
+    The wiki access level for this group.
+    """
     wiki_access_level = String()
+
+    """
+    The repository storage location for this group.
+    """
     repository_storage = String()
+
+    """
+    Whether GitLab Duo features are enabled.
+    """
     duo_features_enabled = Boolean()
+
+    """
+    Whether GitLab Duo features setting is locked.
+    """
     lock_duo_features_enabled = Boolean()
+
+    """
+    Groups that this group is shared with.
+    """
     shared_with_groups = Json()
+
+    """
+    The runners registration token for this group.
+
+    Used to register new runners with this group.
+    """
     runners_token = String()
+
+    """
+    The enabled Git access protocol.
+
+    Values: "ssh", "http", "all".
+    """
     enabled_git_access_protocol = String()
+
+    """
+    Whether sharing groups outside the hierarchy is prevented.
+    """
     prevent_sharing_groups_outside_hierarchy = Boolean()
+
+    """
+    The shared runners compute minutes limit for this group.
+    """
     shared_runners_minutes_limit = Integer()
+
+    """
+    Extra shared runners compute minutes for this group.
+    """
     extra_shared_runners_minutes_limit = Integer()
+
+    """
+    Whether forking projects outside the group is prevented.
+    """
     prevent_forking_outside_group = Boolean()
+
+    """
+    Whether service access token expiration is enforced.
+    """
     service_access_tokens_expiration_enforced = Boolean()
+
+    """
+    Whether membership changes are locked.
+    """
     membership_lock = Boolean()
+
+    """
+    IP address ranges allowed to access this group.
+    """
     ip_restriction_ranges = Json()
+
+    """
+    Limit for unique project downloads.
+    """
     unique_project_download_limit = String()
+
+    """
+    Interval in seconds for unique project download limit.
+    """
     unique_project_download_limit_interval_in_seconds = Integer()
+
+    """
+    List of users to alert when download limit is exceeded.
+    """
     unique_project_download_limit_alertlist = Json()
+
+    """
+    Whether to auto-ban users on excessive project downloads.
+    """
     auto_ban_user_on_excessive_projects_download = Boolean()
 
+    """
+    Reference to the parent group.
+    """
     parent_id = BelongsToSelf()
+
+    """
+    The parent group model.
+    """
     parent = BelongsToModel("parent_id")
+
     ### Search params
+
+    """
+    List of group IDs to exclude from results.
+    """
     skip_groups = Json()
+
+    """
+    Whether to include all available groups.
+    """
     all_available = Boolean()
+
+    """
+    Search query to filter groups by name or path.
+    """
     search = String()
+
+    """
+    Field to order results by.
+    """
     order_by = String()
+
+    """
+    Sort direction (asc or desc).
+    """
     sort = String()
+
+    """
+    Filter by visibility level.
+    """
     visibility = Select(allowed_values=["public", "internal", "private"])
+
+    """
+    Whether to include custom attributes in the response.
+    """
     with_custom_attributes = Boolean()
+
+    """
+    Whether to only return groups owned by the current user.
+    """
     owned = Boolean()
+
+    """
+    Minimum access level required to include a group.
+    """
     min_access_level = Integer()
+
+    """
+    Whether to only return top-level groups.
+    """
     top_level_only = Boolean()
+
+    """
+    Filter by repository storage location.
+    """
     repository_storage = String()
+
+    """
+    Filter by deletion date.
+    """
     marked_for_deletion_on = Datetime(date_format="%Y-%m-%d")

clearskies_gitlab/rest/models/gitlab_rest_group_member.py

@@ -11,7 +11,41 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 class GitlabRestGroupMember(
     gitlab_member.GitlabMember,
 ):
-    """Model for group members."""
+    """
+    Model for GitLab group members.
+
+    This model provides access to the GitLab Group Members API for managing
+    user membership in groups. It allows listing, adding, updating, and removing
+    members from a group.
+
+    See https://docs.gitlab.com/api/members/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestGroupMember
+
+
+    def my_function(group_members: GitlabRestGroupMember):
+        # List all members of a group
+        for member in group_members.where("group_id=123"):
+            print(f"Member: {member.username}, Access Level: {member.access_level}")
+
+        # Find a specific member
+        admin = group_members.find("username=admin")
+        if admin:
+            print(f"Admin access level: {admin.access_level}")
+
+        # Add a new member
+        new_member = group_members.create(
+            {
+                "group_id": "123",
+                "user_id": 456,
+                "access_level": 30,  # Developer
+            }
+        )
+    ```
+    """
 
     id_column_name = "id"
     backend = GitlabRestBackend()
@@ -21,9 +55,38 @@ class GitlabRestGroupMember(
         """Return the slug of the api endpoint for this model."""
         return "groups/:group_id/members"
 
+    """
+    The ID of the group to list members for.
+
+    Used to scope API requests to a specific group.
+    """
     group_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 usage information in the response.
+
+    Only available for groups with a paid subscription.
+    """
     show_seat_info = Boolean()
+
+    """
+    Whether to include inherited members from parent groups.
+
+    When True, returns all members including those inherited from parent groups.
+    """
     all = Boolean()

clearskies_gitlab/rest/models/gitlab_rest_group_project.py

@@ -8,7 +8,33 @@ from clearskies_gitlab.rest.models import gitlab_rest_project
 class GitlabRestGroupProject(
     gitlab_rest_project.GitlabRestProject,
 ):
-    """Model for groups projects."""
+    """
+    Model for projects within a GitLab group.
+
+    This model extends GitlabRestProject to provide access to projects scoped
+    to a specific group. It inherits all project fields and adds group-specific
+    filtering capabilities.
+
+    See https://docs.gitlab.com/api/groups/#list-a-groups-projects for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestGroupProject
+
+
+    def my_function(group_projects: GitlabRestGroupProject):
+        # List all projects in a group
+        for project in group_projects.where("group_id=123"):
+            print(f"Project: {project.name}")
+            print(f"Path: {project.path_with_namespace}")
+
+        # Find a specific project in the group
+        my_project = group_projects.find("name=my-project")
+        if my_project:
+            print(f"Found project: {my_project.web_url}")
+    ```
+    """
 
     @classmethod
     def destination_name(cls: type[Self]) -> str:

clearskies_gitlab/rest/models/gitlab_rest_group_search.py

@@ -10,11 +10,40 @@ from clearskies_gitlab.rest.models import gitlab_rest_advanced_search
 class GitlabRestGroupSearch(
     gitlab_rest_advanced_search.GitlabRestAdvancedSearch,
 ):
-    """Model for groups access tokens."""
+    """
+    Model for GitLab group-scoped search.
+
+    This model extends GitlabRestAdvancedSearch to provide search functionality
+    scoped to a specific group. It allows searching for content within a group
+    and its projects.
+
+    See https://docs.gitlab.com/api/search/#group-search-api for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestGroupSearch
+
+
+    def my_function(group_search: GitlabRestGroupSearch):
+        # Search for issues within a group
+        for result in group_search.where("group_id=123").where("scope=issues").where("search=bug"):
+            print(f"Found issue: {result.fields}")
+
+        # Search for code within a group
+        for result in group_search.where("group_id=123").where("scope=blobs").where("search=TODO"):
+            print(f"Found code match: {result.fields}")
+    ```
+    """
 
     @classmethod
     def destination_name(cls: type[Self]) -> str:
         """Return the slug of the api endpoint for this model."""
         return "groups/:group_id/search"
 
+    """
+    The ID of the group to search within.
+
+    Limits the search scope to this group and its projects.
+    """
     group_id = Integer()

clearskies_gitlab/rest/models/gitlab_rest_group_search_blob.py

@@ -10,4 +10,30 @@ class GitlabRestGroupSearchBlob(
     gitlab_rest_group_search.GitlabRestGroupSearch,
     gitlab_rest_advanced_search_blob.GitlabRestAdvancedSearchBlob,
 ):
-    """Model for advanced searching blobs."""
+    """
+    Model for GitLab group-scoped blob search results.
+
+    This model combines GitlabRestGroupSearch and GitlabRestAdvancedSearchBlob
+    to provide blob (code/file) search functionality scoped to a specific group.
+    It includes all the blob-specific fields like path, filename, and line numbers.
+
+    See https://docs.gitlab.com/api/search/#scope-blobs for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestGroupSearchBlob
+
+
+    def my_function(group_blob_search: GitlabRestGroupSearchBlob):
+        # Search for code within a group
+        for blob in (
+            group_blob_search.where("group_id=123")
+            .where("scope=blobs")
+            .where("search=def authenticate")
+        ):
+            print(f"Found in {blob.path} at line {blob.startline}")
+            print(f"Project ID: {blob.project_id}")
+            print(f"Content: {blob.data}")
+    ```
+    """

clearskies_gitlab/rest/models/gitlab_rest_group_subgroup.py

@@ -16,48 +16,85 @@ from clearskies_gitlab.rest.models import (
 class GitlabRestGroupSubgroup(
     gitlab_rest_group_base.GitlabRestGroupBase,
 ):
-    """Model for Subgroups."""
+    """
+    Model for GitLab subgroups.
 
-    # id_column_name = "group_id"
+    This model provides access to subgroups within a parent group. Subgroups
+    allow for hierarchical organization of projects and teams within GitLab.
+
+    See https://docs.gitlab.com/api/groups/#list-a-groups-subgroups for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestGroupSubgroup
+
+
+    def my_function(subgroups: GitlabRestGroupSubgroup):
+        # List all subgroups of a parent group
+        for subgroup in subgroups.where("group_id=123"):
+            print(f"Subgroup: {subgroup.name}")
+            print(f"Full path: {subgroup.full_path}")
+
+            # Access nested subgroups
+            for nested in subgroup.subgroups:
+                print(f"  Nested: {nested.name}")
+
+        # Find a specific subgroup
+        team = subgroups.find("path=my-team")
+        if team:
+            for project in team.projects:
+                print(f"Project: {project.name}")
+    ```
+    """
 
     @classmethod
     def destination_name(cls: type[Self]) -> str:
         """Return the slug of the api endpoint for this model."""
         return "groups/:group_id/subgroups"
 
+    """
+    The ID of the parent group.
+
+    Used to scope API requests to subgroups of a specific parent group.
+    """
     group_id = String()
 
+    """
+    Projects belonging to this subgroup.
+    """
     projects = HasMany(
         gitlab_rest_group_project_reference.GitlabRestGroupProjectReference,
         foreign_column_name="group_id",
     )
+
+    """
+    Access tokens for this subgroup.
+    """
     access_tokens = HasMany(
         gitlab_rest_group_access_token_reference.GitlabRestGroupAccessTokenReference,
         foreign_column_name="group_id",
     )
+
+    """
+    CI/CD variables defined for this subgroup.
+    """
     variables = HasMany(
         gitlab_rest_group_variable_reference.GitlabRestGroupVariableReference,
         foreign_column_name="group_id",
     )
+
+    """
+    Nested subgroups within this subgroup.
+    """
     subgroups = HasManySelf(
         foreign_column_name="group_id",
     )
+
+    """
+    Members of this subgroup.
+    """
     members = HasMany(
         gitlab_rest_group_member_reference.GitlabRestGroupMemberReference,
         foreign_column_name="group_id",
     )
-    # parent_id = BelongsToSelf()
-    # parent = BelongsToModel("parent_id")
-    # ### Search params
-    # skip_groups = Json()
-    # all_available = Boolean()
-    # search = String()
-    # order_by = String()
-    # sort = String()
-    # visibility = Select(allowed_values=["public", "internal", "private"])
-    # with_custom_attributes = Boolean()
-    # owned = Boolean()
-    # min_access_level = Integer()
-    # top_level_only = Boolean()
-    # repository_storage = String()
-    # marked_for_deletion_on = Datetime(date_format="%Y-%m-%d")