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

clearskies_gitlab/rest/gitlab_member.py

@@ -5,17 +5,96 @@ from clearskies.columns import Datetime, Email, Integer, Json, String
 
 
 class GitlabMember(Model):
-    """Base model for group or project members."""
+    """
+    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()

clearskies_gitlab/rest/models/gitlab_rest_advanced_search.py

@@ -9,7 +9,33 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 
 
 class GitlabRestAdvancedSearch(Model):
-    """Model for advanced search."""
+    """
+    Model for GitLab Advanced Search.
+
+    This model provides access to GitLab's Advanced Search API, which allows searching across
+    the entire GitLab instance for various types of content including projects, issues,
+    merge requests, milestones, snippets, users, wiki content, commits, blobs, and notes.
+
+    Advanced Search requires Elasticsearch to be configured on the GitLab instance.
+
+    See https://docs.gitlab.com/api/search/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestAdvancedSearch
+
+
+    def my_function(search: GitlabRestAdvancedSearch):
+        # Search for projects matching a query
+        for result in search.where("scope=projects").where("search=my-project"):
+            print(f"Found: {result.fields}")
+
+        # Search for blobs (code) containing specific text
+        for result in search.where("scope=blobs").where("search=def my_function"):
+            print(f"Found code match: {result.fields}")
+    ```
+    """
 
     backend = GitlabRestBackend()
 
@@ -18,6 +44,21 @@ class GitlabRestAdvancedSearch(Model):
         """Return the slug of the api endpoint for this model."""
         return "search"
 
+    """
+    The scope of the search.
+
+    Determines what type of content to search for. Available values:
+    - `projects`: Search for projects
+    - `issues`: Search for issues
+    - `merge_requests`: Search for merge requests
+    - `milestones`: Search for milestones
+    - `snippet_titles`: Search for snippet titles
+    - `users`: Search for users
+    - `wiki_blobs`: Search for wiki content
+    - `commits`: Search for commits
+    - `blobs`: Search for code/file content
+    - `notes`: Search for comments/notes
+    """
     scope = Select(
         allowed_values=[
             "projects",
@@ -32,7 +73,32 @@ class GitlabRestAdvancedSearch(Model):
             "notes",
         ]
     )
+
+    """
+    The search query string.
+
+    The text to search for across the selected scope.
+    """
     search = String()
+
+    """
+    Filter for confidential issues.
+
+    When searching issues, set to `True` to only return confidential issues,
+    or `False` to only return non-confidential issues.
+    """
     confidential = Boolean()
+
+    """
+    Filter by state.
+
+    When searching issues or merge requests, filter by their state (e.g., "opened", "closed").
+    """
     state = String()
+
+    """
+    Additional fields returned in the search results.
+
+    Contains extra data specific to the search scope, returned as a JSON object.
+    """
     fields = Json()

clearskies_gitlab/rest/models/gitlab_rest_advanced_search_blob.py

@@ -8,16 +8,87 @@ from clearskies_gitlab.rest.models import gitlab_rest_advanced_search, gitlab_re
 class GitlabRestAdvancedSearchBlob(
     gitlab_rest_advanced_search.GitlabRestAdvancedSearch,
 ):
-    """Model for advanced searching blobs."""
+    """
+    Model for GitLab Advanced Search blob results.
 
+    This model extends GitlabRestAdvancedSearch to provide specific fields for blob (code/file)
+    search results. When searching with `scope="blobs"`, the results include file content
+    and location information.
+
+    See https://docs.gitlab.com/api/search/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestAdvancedSearchBlob
+
+
+    def my_function(blob_search: GitlabRestAdvancedSearchBlob):
+        # Search for code containing a specific function
+        for blob in blob_search.where("scope=blobs").where("search=def authenticate"):
+            print(f"Found in {blob.path} at line {blob.startline}")
+            print(f"Project ID: {blob.project_id}")
+    ```
+    """
+
+    """
+    The base filename without the directory path.
+
+    For example, if the full path is "src/utils/helpers.py", the basename would be "helpers.py".
+    """
     basename = String()
+
+    """
+    The matching content from the file.
+
+    Contains the actual code or text that matched the search query, typically with
+    surrounding context.
+    """
     data = String()
+
+    """
+    The full path to the file within the repository.
+
+    For example: "src/utils/helpers.py".
+    """
     path = String()
+
+    """
+    The filename of the matched file.
+
+    Similar to basename, contains the name of the file.
+    """
     filename = String()
+
+    """
+    The unique identifier for this search result.
+    """
     id = Integer()
+
+    """
+    The Git reference (branch or tag) where the match was found.
+
+    For example: "main", "develop", or "v1.0.0".
+    """
     ref = String()
+
+    """
+    The starting line number of the matched content.
+
+    Indicates where in the file the matching content begins.
+    """
     startline = Integer()
+
+    """
+    The ID of the project containing the matched file.
+    """
     project_id = BelongsToId(
         gitlab_rest_project.GitlabRestProject,
     )
+
+    """
+    The project model containing the matched file.
+
+    Provides access to the full project object via the relationship.
+    """
     project = BelongsToModel("project_id")

clearskies_gitlab/rest/models/gitlab_rest_current_user.py

@@ -11,7 +11,30 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 class GitlabRestCurrentUser(
     Model,
 ):
-    """Model for current user."""
+    """
+    Model for the current authenticated GitLab user.
+
+    This model provides access to the GitLab User API for retrieving information about
+    the currently authenticated user. It returns detailed profile information including
+    identity, settings, and capabilities.
+
+    See https://docs.gitlab.com/api/users/#for-normal-users for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestCurrentUser
+
+
+    def my_function(current_user: GitlabRestCurrentUser):
+        # Get the current user's information
+        user = current_user.first()
+        if user:
+            print(f"Logged in as: {user.username}")
+            print(f"Email: {user.email}")
+            print(f"Can create projects: {user.can_create_project}")
+    ```
+    """
 
     id_column_name = "id"
     backend = GitlabRestBackend()
@@ -21,26 +44,136 @@ class GitlabRestCurrentUser(
         """Return the slug of the api endpoint for this model."""
         return "user"
 
+    """
+    The unique identifier for the user.
+    """
     id = Integer()
+
+    """
+    The username of the user.
+
+    This is the unique handle used for login and mentions (e.g., @username).
+    """
     username = String()
+
+    """
+    The primary email address of the user.
+    """
     email = Email()
+
+    """
+    The display name of the user.
+    """
     name = String()
+
+    """
+    The current state of the user account.
+
+    Common values include "active", "blocked", "deactivated".
+    """
     state = String()
+
+    """
+    Whether the user account is locked.
+
+    A locked account cannot sign in until unlocked by an administrator.
+    """
     locked = Boolean()
+
+    """
+    URL to the user's avatar image.
+    """
     avatar_url = String()
+
+    """
+    URL to the user's GitLab profile page.
+    """
     web_url = String()
+
+    """
+    The date and time when the user account was created.
+    """
     created_at = Datetime()
+
+    """
+    The user's biography/description.
+
+    A short text that appears on the user's profile page.
+    """
     bio = String()
+
+    """
+    The user's public email address.
+
+    This email is visible to other users on the profile page.
+    """
     public_email = Email()
+
+    """
+    The organization the user belongs to.
+    """
     organization = String()
+
+    """
+    Whether this user is a bot account.
+
+    Bot accounts are typically used for automation and CI/CD.
+    """
     bot = Boolean()
+
+    """
+    The date and time of the user's last sign in.
+    """
     last_sign_in_at = Datetime()
+
+    """
+    The date and time when the user's email was confirmed.
+    """
     confirmed_at = Datetime()
+
+    """
+    The date of the user's last activity.
+    """
     last_activity_on = Datetime()
+
+    """
+    Array of identity provider information.
+
+    Contains details about external identity providers (LDAP, SAML, etc.)
+    linked to this account.
+    """
     identities = Json()
+
+    """
+    Whether the user can create new groups.
+    """
     can_create_group = Boolean()
+
+    """
+    Whether the user can create new projects.
+    """
     can_create_project = Boolean()
+
+    """
+    Whether two-factor authentication is enabled for this user.
+    """
     two_factor_enabled = Boolean()
+
+    """
+    Whether this is an external user.
+
+    External users have limited access to internal projects.
+    """
     external = Boolean()
+
+    """
+    Whether the user has a private profile.
+
+    Private profiles hide activity and contribution information.
+    """
     private_profile = Boolean()
+
+    """
+    The email address used for Git commits.
+    """
     commit_email = Email()

clearskies_gitlab/rest/models/gitlab_rest_group.py

@@ -19,29 +19,88 @@ from clearskies_gitlab.rest.models import (
 class GitlabRestGroup(
     gitlab_rest_group_base.GitlabRestGroupBase,
 ):
-    """Model for groups."""
+    """
+    Model for GitLab groups.
+
+    This model provides access to the GitLab Groups API for managing groups and their
+    associated resources. Groups are used to organize projects and manage permissions
+    for teams of users.
+
+    See https://docs.gitlab.com/api/groups/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestGroup
+
+
+    def my_function(groups: GitlabRestGroup):
+        # List all groups
+        for group in groups:
+            print(f"Group: {group.name} ({group.full_path})")
+
+        # Find a specific group
+        my_group = groups.find("path=my-team")
+        if my_group:
+            # Access related resources
+            for project in my_group.projects:
+                print(f"Project: {project.name}")
+
+            for member in my_group.members:
+                print(f"Member: {member.username}")
+    ```
+    """
 
     @classmethod
     def destination_name(cls: type[Self]) -> str:
         """Return the slug of the api endpoint for this model."""
         return "groups"
 
+    """
+    Projects belonging to this group.
+
+    Provides access to all projects within the group.
+    """
     projects = HasMany(
         gitlab_rest_group_project_reference.GitlabRestGroupProjectReference,
         foreign_column_name="group_id",
     )
+
+    """
+    Access tokens for this group.
+
+    Group access tokens can be used for API authentication with group-level permissions.
+    """
     access_tokens = HasMany(
         gitlab_rest_group_access_token_reference.GitlabRestGroupAccessTokenReference,
         foreign_column_name="group_id",
     )
+
+    """
+    CI/CD variables defined for this group.
+
+    These variables are available to all projects within the group.
+    """
     variables = HasMany(
         gitlab_rest_group_variable_reference.GitlabRestGroupVariableReference,
         foreign_column_name="group_id",
     )
+
+    """
+    Subgroups within this group.
+
+    Groups can be nested to create a hierarchy of teams and projects.
+    """
     subgroups = HasMany(
         gitlab_rest_group_subgroup_reference.GitlabRestGroupSubgroupReference,
         foreign_column_name="group_id",
     )
+
+    """
+    Members of this group.
+
+    Users who have been granted access to the group and its resources.
+    """
     members = HasMany(
         gitlab_rest_group_member_reference.GitlabRestGroupMemberReference,
         foreign_column_name="group_id",

clearskies_gitlab/rest/models/gitlab_rest_group_access_token.py

@@ -11,7 +11,40 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 class GitlabRestGroupAccessToken(
     Model,
 ):
-    """Model for groups access tokens."""
+    """
+    Model for GitLab group access tokens.
+
+    This model provides access to the GitLab Group Access Tokens API for managing
+    access tokens at the group level. Group access tokens can be used for API
+    authentication with permissions scoped to a specific group.
+
+    See https://docs.gitlab.com/api/group_access_tokens/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestGroupAccessToken
+
+
+    def my_function(access_tokens: GitlabRestGroupAccessToken):
+        # List all access tokens for a group
+        for token in access_tokens.where("group_id=123"):
+            print(f"Token: {token.name}, Active: {token.active}")
+            print(f"Expires: {token.expires_at}")
+
+        # Create a new access token
+        new_token = access_tokens.create(
+            {
+                "group_id": "123",
+                "name": "CI Token",
+                "scopes": ["read_api", "read_repository"],
+                "expires_at": "2025-12-31",
+                "access_level": 30,
+            }
+        )
+        print(f"New token: {new_token.token}")
+    ```
+    """
 
     id_column_name = "id"
     backend = GitlabRestBackend()
@@ -21,14 +54,82 @@ class GitlabRestGroupAccessToken(
         """Return the slug of the api endpoint for this model."""
         return "groups/:group_id/access_tokens"
 
+    """
+    The ID of the group this token belongs to.
+
+    Used to scope API requests to a specific group.
+    """
     group_id = String()
+
+    """
+    The unique identifier for the access token.
+    """
     id = Integer()
+
+    """
+    The user ID associated with this token.
+
+    Each access token is associated with a bot user account.
+    """
     user_id = Integer()
+
+    """
+    The name/description of the access token.
+
+    A human-readable identifier for the token's purpose.
+    """
     name = String()
+
+    """
+    The date and time when the token was created.
+    """
     created_at = Datetime()
+
+    """
+    The expiration date of the token.
+
+    After this date, the token will no longer be valid for authentication.
+    Format: YYYY-MM-DD
+    """
     expires_at = Datetime(date_format="%Y-%m-%d")
+
+    """
+    Whether the token is currently active.
+
+    Inactive tokens cannot be used for authentication.
+    """
     active = Boolean()
+
+    """
+    Whether the token has been revoked.
+
+    Revoked tokens are permanently disabled.
+    """
     revoked = Boolean()
+
+    """
+    The access level granted by this token.
+
+    Common values:
+    - 10: Guest
+    - 20: Reporter
+    - 30: Developer
+    - 40: Maintainer
+    - 50: Owner
+    """
     access_level = Integer()
+
+    """
+    The actual token value.
+
+    This is only returned when creating a new token and should be stored securely.
+    It cannot be retrieved again after creation.
+    """
     token = String()
+
+    """
+    The scopes/permissions granted to this token.
+
+    Array of scope strings like "api", "read_api", "read_repository", etc.
+    """
     scopes = Json()