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

clearskies_gitlab/rest/models/gitlab_rest_project_repository_commit_diff.py

@@ -11,7 +11,38 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 class GitlabRestProjectRepositoryCommitDiff(
     Model,
 ):
-    """Model for projects repository commits diff."""
+    r"""
+    Model for GitLab project repository commit diffs.
+
+    This model provides access to the GitLab Commits API for retrieving
+    the diff (file changes) of a specific commit. Each diff entry represents
+    changes to a single file.
+
+    See https://docs.gitlab.com/api/commits/#get-the-diff-of-a-commit for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectRepositoryCommitDiff
+
+
+    def my_function(diffs: GitlabRestProjectRepositoryCommitDiff):
+        # Get diff for a specific commit
+        for diff in diffs.where("project_id=123&commit_id=abc123"):
+            print(f"File: {diff.new_path}")
+            if diff.new_file:
+                print("  (new file)")
+            elif diff.deleted_file:
+                print("  (deleted)")
+            elif diff.renamed_file:
+                print(f"  (renamed from {diff.old_path})")
+            print(f"Diff:\n{diff.diff}")
+
+        # Get unified diff format
+        for diff in diffs.where("project_id=123&commit_id=abc123&unidiff=true"):
+            print(diff.diff)
+    ```
+    """
 
     id_column_name = "commit_id"
 
@@ -22,15 +53,71 @@ class GitlabRestProjectRepositoryCommitDiff(
         """Return the slug of the api endpoint for this model."""
         return "projects/:project_id/repository/commits/:commit_id/diff"
 
+    """
+    The diff content showing the changes.
+
+    Contains the unified diff format showing additions and deletions.
+    """
     diff = String()
+
+    """
+    The new file path after the commit.
+
+    For renamed files, this is the destination path.
+    """
     new_path = String()
+
+    """
+    The old file path before the commit.
+
+    For renamed files, this is the source path.
+    """
     old_path = String()
+
+    """
+    The file mode before the change.
+
+    Unix file permission mode (e.g., 100644 for regular file).
+    """
     a_mode = Integer()
+
+    """
+    The file mode after the change.
+
+    Unix file permission mode (e.g., 100644 for regular file).
+    """
     b_mode = Integer()
+
+    """
+    Whether this is a newly created file.
+    """
     new_file = Boolean()
+
+    """
+    Whether this file was renamed.
+    """
     renamed_file = Boolean()
+
+    """
+    Whether this file was deleted.
+    """
     deleted_file = Boolean()
-    # search params
+
+    ### Search params
+
+    """
+    The ID of the project containing the commit.
+    """
     project_id = Integer()
+
+    """
+    The SHA hash of the commit to get the diff for.
+    """
     commit_id = String()
+
+    """
+    Whether to return the diff in unified diff format.
+
+    When true, returns a more standard unified diff format.
+    """
     unidiff = Boolean()

clearskies_gitlab/rest/models/gitlab_rest_project_repository_contributor.py

@@ -12,7 +12,35 @@ from clearskies_gitlab.rest.models import gitlab_rest_project_reference
 class GitlabRestProjectRepositoryContributor(
     Model,
 ):
-    """Model for projects repository contributors."""
+    """
+    Model for GitLab project repository contributors.
+
+    This model provides access to the GitLab Repository Contributors API for
+    retrieving statistics about contributors to a project's repository.
+    Contributors are identified by their commit email address.
+
+    See https://docs.gitlab.com/api/repositories/#contributors for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectRepositoryContributor
+
+
+    def my_function(contributors: GitlabRestProjectRepositoryContributor):
+        # List all contributors to a project
+        for contributor in contributors.where("project_id=123"):
+            print(f"Contributor: {contributor.name}")
+            print(f"Email: {contributor.email}")
+            print(f"Commits: {contributor.commits}")
+            print(f"Lines added: {contributor.additions}")
+            print(f"Lines deleted: {contributor.deletions}")
+
+        # Get contributors for a specific branch
+        for contributor in contributors.where("project_id=123&ref=develop"):
+            print(f"{contributor.name}: {contributor.commits} commits")
+    ```
+    """
 
     id_column_name = "email"
 
@@ -23,12 +51,50 @@ class GitlabRestProjectRepositoryContributor(
         """Return the slug of the api endpoint for this model."""
         return "projects/:project_id/repository/contributors"
 
+    """
+    The display name of the contributor.
+
+    This is taken from the Git commit author name.
+    """
     name = String()
+
+    """
+    The email address of the contributor.
+
+    This is taken from the Git commit author email and serves as the unique identifier.
+    """
     email = Email()
+
+    """
+    The total number of commits by this contributor.
+    """
     commits = Integer()
+
+    """
+    The total number of lines added by this contributor.
+    """
     additions = Integer()
+
+    """
+    The total number of lines deleted by this contributor.
+    """
     deletions = Integer()
-    # search params
+
+    ### Search params
+
+    """
+    The ID of the project to query contributors for.
+    """
     project_id = BelongsToId(gitlab_rest_project_reference.GitlabRestProjectReference)
+
+    """
+    The project model this contributor belongs to.
+    """
     project = BelongsToModel("project_id")
+
+    """
+    The branch or tag to get contributors for.
+
+    Defaults to the default branch if not specified.
+    """
     ref = String()

clearskies_gitlab/rest/models/gitlab_rest_project_repository_file.py

@@ -12,7 +12,37 @@ from clearskies_gitlab.rest.models import gitlab_rest_project_reference
 class GitlabRestProjectRepositoryFile(
     Model,
 ):
-    """Model for projects repository commits diff."""
+    """
+    Model for GitLab project repository files.
+
+    This model provides access to the GitLab Repository Files API for
+    retrieving file metadata and content from a project's repository.
+    Files are identified by their path within the repository.
+
+    See https://docs.gitlab.com/api/repository_files/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectRepositoryFile
+
+
+    def my_function(files: GitlabRestProjectRepositoryFile):
+        # Get a specific file from the repository
+        readme = files.find("project_id=123&file_path=README.md")
+        if readme:
+            print(f"File: {readme.file_name}")
+            print(f"Size: {readme.size} bytes")
+            print(f"Encoding: {readme.encoding}")
+            # Content is base64 encoded by default
+            print(f"Content: {readme.content}")
+
+        # Get a file from a specific branch
+        config = files.find("project_id=123&file_path=config.yml&ref=develop")
+        if config:
+            print(f"Last commit: {config.last_commit_id}")
+    ```
+    """
 
     id_column_name = "file_path"
 
@@ -23,17 +53,76 @@ class GitlabRestProjectRepositoryFile(
         """Return the slug of the api endpoint for this model."""
         return "projects/:project_id/repository/files/:file_path"
 
+    """
+    The ID of the project containing the file.
+    """
     project_id = BelongsToId(gitlab_rest_project_reference.GitlabRestProjectReference)
+
+    """
+    The project model this file belongs to.
+    """
     project = BelongsToModel("project_id")
 
+    """
+    The path to the file within the repository.
+
+    This serves as the unique identifier for the file.
+    """
     file_path = String()
+
+    """
+    The branch, tag, or commit SHA to retrieve the file from.
+
+    Defaults to HEAD (the default branch).
+    """
     ref = String(default="HEAD")
+
+    """
+    The blob SHA of the file content.
+    """
     blob_id = String()
+
+    """
+    The commit SHA where this file was last modified.
+    """
     commit_id = String()
+
+    """
+    The file content.
+
+    By default, this is base64 encoded. Use the encoding field
+    to determine how to decode it.
+    """
     content = String()
+
+    """
+    The SHA256 hash of the file content.
+    """
     content_sha256 = String()
+
+    """
+    The encoding of the content field.
+
+    Typically "base64" for binary-safe transfer.
+    """
     encoding = String()
+
+    """
+    Whether the file has the executable permission set.
+    """
     execute_filemode = Boolean()
+
+    """
+    The name of the file (without path).
+    """
     file_name = String()
+
+    """
+    The commit SHA of the last commit that modified this file.
+    """
     last_commit_id = String()
+
+    """
+    The size of the file in bytes.
+    """
     size = Integer()

clearskies_gitlab/rest/models/gitlab_rest_project_repository_file_raw.py

@@ -9,10 +9,39 @@ from clearskies_gitlab.rest.backends import GitlabRestBackend
 from clearskies_gitlab.rest.models import gitlab_rest_project_reference
 
 
-class GitlabRestProjectRepositoryCommitDiff(
+class GitlabRestProjectRepositoryFileRaw(
     Model,
 ):
-    """Model for projects repository commits diff."""
+    """
+    Model for GitLab project repository raw file content.
+
+    This model provides access to the GitLab Repository Files API for
+    retrieving raw file content from a project's repository. Unlike the
+    regular file endpoint, this returns the raw file content without
+    base64 encoding.
+
+    See https://docs.gitlab.com/api/repository_files/#get-raw-file-from-repository for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectRepositoryFileRaw
+
+
+    def my_function(raw_files: GitlabRestProjectRepositoryFileRaw):
+        # Get raw content of a file
+        readme = raw_files.find("project_id=123&file_path=README.md")
+        if readme:
+            # Content is returned as-is, not base64 encoded
+            print(readme.content)
+
+        # Get raw content from a specific branch
+        config = raw_files.find("project_id=123&file_path=config.yml&ref=develop")
+
+        # Get LFS pointer content
+        large_file = raw_files.find("project_id=123&file_path=data.bin&lfs=true")
+    ```
+    """
 
     id_column_name = "file_path"
 
@@ -21,11 +50,36 @@ class GitlabRestProjectRepositoryCommitDiff(
     @classmethod
     def destination_name(cls: type[Self]) -> str:
         """Return the slug of the api endpoint for this model."""
-        return "projects/:project_id/repository/files/:file_path"
+        return "projects/:project_id/repository/files/:file_path/raw"
 
+    """
+    The ID of the project containing the file.
+    """
     project_id = BelongsToId(gitlab_rest_project_reference.GitlabRestProjectReference)
+
+    """
+    The project model this file belongs to.
+    """
     project = BelongsToModel("project_id")
 
+    """
+    The path to the file within the repository.
+
+    This serves as the unique identifier for the file.
+    """
     file_path = String()
+
+    """
+    The branch, tag, or commit SHA to retrieve the file from.
+
+    Defaults to HEAD (the default branch).
+    """
     ref = String(default="HEAD")
+
+    """
+    Whether to return the LFS pointer content.
+
+    When true and the file is stored in Git LFS, returns the
+    LFS pointer file content instead of the actual file.
+    """
     lfs = Boolean()

clearskies_gitlab/rest/models/gitlab_rest_project_variable.py

@@ -12,7 +12,45 @@ from clearskies_gitlab.rest.models import gitlab_rest_project_reference
 class GitlabRestProjectVariable(
     gitlab_cicd_variable.GitlabCICDVariable,
 ):
-    """Model for gitlab group variables."""
+    """
+    Model for GitLab project CI/CD variables.
+
+    This model provides access to the GitLab Project Variables API for managing
+    CI/CD variables at the project level. It extends the base GitlabCICDVariable
+    class with project-specific functionality.
+
+    See https://docs.gitlab.com/api/project_level_variables/ for more details.
+
+    Example usage:
+
+    ```python
+    from clearskies_gitlab.rest.models import GitlabRestProjectVariable
+
+
+    def my_function(variables: GitlabRestProjectVariable):
+        # List all variables for a project
+        for var in variables.where("project_id=123"):
+            print(f"Variable: {var.key}")
+            print(f"Protected: {var.protected}")
+            print(f"Masked: {var.masked}")
+
+        # Get a specific variable
+        api_key = variables.find("project_id=123&key=API_KEY")
+        if api_key:
+            print(f"Value: {api_key.value}")
+
+        # Create a new variable
+        variables.create(
+            {
+                "project_id": 123,
+                "key": "NEW_VAR",
+                "value": "secret_value",
+                "protected": True,
+                "masked": True,
+            }
+        )
+    ```
+    """
 
     backend = GitlabRestBackend()
     id_column_name = "key"
@@ -22,5 +60,12 @@ class GitlabRestProjectVariable(
         """Return the slug of the api endpoint for this model."""
         return "projects/:project_id/variables"
 
+    """
+    The ID of the project this variable belongs to.
+    """
     project_id = BelongsToId(gitlab_rest_project_reference.GitlabRestProjectReference)
+
+    """
+    The project model this variable belongs to.
+    """
     project = BelongsToModel("project_id")