gitlab-projects-settings 4.0.0__tar.gz → 4.2.0__tar.gz

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/CHANGELOG.md

@@ -1,4 +1,27 @@
 
+<a name="4.2.0"></a>
+## [4.2.0](https://gitlab.com/AdrianDC/gitlab-projects-settings/compare/4.1.0...4.2.0) (2024-05-27)
+
+### Documentation
+
+* **readme:** add 'gitlab-projects-settings' examples documentation
+
+### Features
+
+* **entrypoint:** improve outputs logs upon delections
+* **main:** show newer updates message upon incompatible arguments
+
+
+<a name="4.1.0"></a>
+## [4.1.0](https://gitlab.com/AdrianDC/gitlab-projects-settings/compare/4.0.0...4.1.0) (2024-05-17)
+
+### Features
+
+* **entrypoint:** implement prompt confirmation upon deletions
+* **gitlab:** isolate 'ProtectionLevels' enumeration
+* **requirements:** prepare 'questionary' library integration
+
+
 <a name="4.0.0"></a>
 ## [4.0.0](https://gitlab.com/AdrianDC/gitlab-projects-settings/compare/3.0.0...4.0.0) (2024-05-15)
 

{gitlab_projects_settings-4.0.0/gitlab_projects_settings.egg-info → gitlab_projects_settings-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gitlab-projects-settings
-Version: 4.0.0
+Version: 4.2.0
 Summary: Configure GitLab groups and projects settings automatically
 Home-page: https://gitlab.com/AdrianDC/gitlab-projects-settings
 Author: Adrian DC
@@ -30,6 +30,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: colored>=1.4.2
 Requires-Dist: python-gitlab>=4.4.0
+Requires-Dist: questionary>=2.0.1
 Requires-Dist: setuptools>=45.1.0
 Requires-Dist: update_checker>=0.18.0
 
@@ -57,6 +58,28 @@ The following step is required before using the tool:
 
 ---
 
+## Examples
+
+<!-- prettier-ignore-start -->
+
+```bash
+# Show the helper menu
+gitlab-projects-settings
+
+# Protect all projects' tags under a group
+gitlab-projects-settings --protect-tags -- 'https://gitlab.com' 'group'
+
+# Update all avatars and descriptions under a group
+gitlab-projects-settings --set-avatar ./avatar.png --update-description 'https://gitlab.com' 'group'
+
+# Automatically detect and reset features of projects based on usage
+gitlab-projects-settings --reset-features 'https://gitlab.com' 'group/project'
+```
+
+<!-- prettier-ignore-end -->
+
+---
+
 ## Usage
 
 <!-- prettier-ignore-start -->
@@ -64,12 +87,12 @@ The following step is required before using the tool:
 
 ```yaml
 usage: gitlab-projects-settings [-h] [--version] [--update-check] [--settings] [--set GROUP KEY VAL] [-t TOKEN]
-                                [--dry-run] [--exclude-group] [--exclude-subgroups] [--exclude-projects]
+                                [--dry-run] [--dump] [--exclude-group] [--exclude-subgroups] [--exclude-projects]
                                 [--available-features] [--reset-features [KEEP_FEATURES]]
                                 [--disable-features FEATURES] [--enable-features FEATURES] [--reset-members]
                                 [--set-avatar FILE] [--set-description TEXT] [--update-description]
                                 [--run-housekeeping] [--archive-project | --unarchive-project] [--delete-group]
-                                [--delete-project] [--protect-branches] [--protect-tags LEVEL] [--]
+                                [--delete-project] [--protect-branches] [--protect-tags [LEVEL]] [--]
                                 [gitlab] [path]
 
 gitlab-projects-settings: Configure GitLab groups and projects settings automatically
@@ -87,6 +110,7 @@ credentials arguments:
 
 common settings arguments:
   --dry-run                         # Enable dry run mode to check without saving
+  --dump                            # Dump Python objects of groups and projects
   --exclude-group                   # Exclude parent group settings
   --exclude-subgroups               # Exclude children subgroups settings
   --exclude-projects                # Exclude children projects settings
@@ -111,7 +135,7 @@ advanced settings arguments:
 
 repository settings arguments:
   --protect-branches                # Protect branches with default master/main, develop and staging
-  --protect-tags LEVEL              # Protect tags at level [no-one,admins,maintainers,developers]
+  --protect-tags [LEVEL]            # Protect tags at level [no-one,admins,maintainers,developers] (default: no-one)
 
 positional arguments:
   --                                # Positional arguments separator (recommended)
@@ -138,10 +162,20 @@ gitlab-projects-settings --settings
 
 ---
 
+## Environment available configurations
+
+`gitlab-projects-settings` uses `colored` for colors outputs and `questionary` for interactive menus.
+
+If colors of both outputs types do not match the terminal's theme,  
+an environment variable `NO_COLOR=1` can be defined to disable colors.
+
+---
+
 ## Dependencies
 
 - [colored](https://pypi.org/project/colored/): Terminal colors and styles
 - [python-gitlab](https://pypi.org/project/python-gitlab/): A python wrapper for the GitLab API
+- [questionary](https://pypi.org/project/questionary/): Interactive terminal user interfaces
 - [setuptools](https://pypi.org/project/setuptools/): Build and manage Python packages
 - [update-checker](https://pypi.org/project/update-checker/): Check for package updates on PyPI
 

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/README.md

@@ -22,6 +22,28 @@ The following step is required before using the tool:
 
 ---
 
+## Examples
+
+<!-- prettier-ignore-start -->
+
+```bash
+# Show the helper menu
+gitlab-projects-settings
+
+# Protect all projects' tags under a group
+gitlab-projects-settings --protect-tags -- 'https://gitlab.com' 'group'
+
+# Update all avatars and descriptions under a group
+gitlab-projects-settings --set-avatar ./avatar.png --update-description 'https://gitlab.com' 'group'
+
+# Automatically detect and reset features of projects based on usage
+gitlab-projects-settings --reset-features 'https://gitlab.com' 'group/project'
+```
+
+<!-- prettier-ignore-end -->
+
+---
+
 ## Usage
 
 <!-- prettier-ignore-start -->
@@ -29,12 +51,12 @@ The following step is required before using the tool:
 
 ```yaml
 usage: gitlab-projects-settings [-h] [--version] [--update-check] [--settings] [--set GROUP KEY VAL] [-t TOKEN]
-                                [--dry-run] [--exclude-group] [--exclude-subgroups] [--exclude-projects]
+                                [--dry-run] [--dump] [--exclude-group] [--exclude-subgroups] [--exclude-projects]
                                 [--available-features] [--reset-features [KEEP_FEATURES]]
                                 [--disable-features FEATURES] [--enable-features FEATURES] [--reset-members]
                                 [--set-avatar FILE] [--set-description TEXT] [--update-description]
                                 [--run-housekeeping] [--archive-project | --unarchive-project] [--delete-group]
-                                [--delete-project] [--protect-branches] [--protect-tags LEVEL] [--]
+                                [--delete-project] [--protect-branches] [--protect-tags [LEVEL]] [--]
                                 [gitlab] [path]
 
 gitlab-projects-settings: Configure GitLab groups and projects settings automatically
@@ -52,6 +74,7 @@ credentials arguments:
 
 common settings arguments:
   --dry-run                         # Enable dry run mode to check without saving
+  --dump                            # Dump Python objects of groups and projects
   --exclude-group                   # Exclude parent group settings
   --exclude-subgroups               # Exclude children subgroups settings
   --exclude-projects                # Exclude children projects settings
@@ -76,7 +99,7 @@ advanced settings arguments:
 
 repository settings arguments:
   --protect-branches                # Protect branches with default master/main, develop and staging
-  --protect-tags LEVEL              # Protect tags at level [no-one,admins,maintainers,developers]
+  --protect-tags [LEVEL]            # Protect tags at level [no-one,admins,maintainers,developers] (default: no-one)
 
 positional arguments:
   --                                # Positional arguments separator (recommended)
@@ -103,10 +126,20 @@ gitlab-projects-settings --settings
 
 ---
 
+## Environment available configurations
+
+`gitlab-projects-settings` uses `colored` for colors outputs and `questionary` for interactive menus.
+
+If colors of both outputs types do not match the terminal's theme,  
+an environment variable `NO_COLOR=1` can be defined to disable colors.
+
+---
+
 ## Dependencies
 
 - [colored](https://pypi.org/project/colored/): Terminal colors and styles
 - [python-gitlab](https://pypi.org/project/python-gitlab/): A python wrapper for the GitLab API
+- [questionary](https://pypi.org/project/questionary/): Interactive terminal user interfaces
 - [setuptools](https://pypi.org/project/setuptools/): Build and manage Python packages
 - [update-checker](https://pypi.org/project/update-checker/): Check for package updates on PyPI
 

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0/gitlab_projects_settings.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gitlab-projects-settings
-Version: 4.0.0
+Version: 4.2.0
 Summary: Configure GitLab groups and projects settings automatically
 Home-page: https://gitlab.com/AdrianDC/gitlab-projects-settings
 Author: Adrian DC
@@ -30,6 +30,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: colored>=1.4.2
 Requires-Dist: python-gitlab>=4.4.0
+Requires-Dist: questionary>=2.0.1
 Requires-Dist: setuptools>=45.1.0
 Requires-Dist: update_checker>=0.18.0
 
@@ -57,6 +58,28 @@ The following step is required before using the tool:
 
 ---
 
+## Examples
+
+<!-- prettier-ignore-start -->
+
+```bash
+# Show the helper menu
+gitlab-projects-settings
+
+# Protect all projects' tags under a group
+gitlab-projects-settings --protect-tags -- 'https://gitlab.com' 'group'
+
+# Update all avatars and descriptions under a group
+gitlab-projects-settings --set-avatar ./avatar.png --update-description 'https://gitlab.com' 'group'
+
+# Automatically detect and reset features of projects based on usage
+gitlab-projects-settings --reset-features 'https://gitlab.com' 'group/project'
+```
+
+<!-- prettier-ignore-end -->
+
+---
+
 ## Usage
 
 <!-- prettier-ignore-start -->
@@ -64,12 +87,12 @@ The following step is required before using the tool:
 
 ```yaml
 usage: gitlab-projects-settings [-h] [--version] [--update-check] [--settings] [--set GROUP KEY VAL] [-t TOKEN]
-                                [--dry-run] [--exclude-group] [--exclude-subgroups] [--exclude-projects]
+                                [--dry-run] [--dump] [--exclude-group] [--exclude-subgroups] [--exclude-projects]
                                 [--available-features] [--reset-features [KEEP_FEATURES]]
                                 [--disable-features FEATURES] [--enable-features FEATURES] [--reset-members]
                                 [--set-avatar FILE] [--set-description TEXT] [--update-description]
                                 [--run-housekeeping] [--archive-project | --unarchive-project] [--delete-group]
-                                [--delete-project] [--protect-branches] [--protect-tags LEVEL] [--]
+                                [--delete-project] [--protect-branches] [--protect-tags [LEVEL]] [--]
                                 [gitlab] [path]
 
 gitlab-projects-settings: Configure GitLab groups and projects settings automatically
@@ -87,6 +110,7 @@ credentials arguments:
 
 common settings arguments:
   --dry-run                         # Enable dry run mode to check without saving
+  --dump                            # Dump Python objects of groups and projects
   --exclude-group                   # Exclude parent group settings
   --exclude-subgroups               # Exclude children subgroups settings
   --exclude-projects                # Exclude children projects settings
@@ -111,7 +135,7 @@ advanced settings arguments:
 
 repository settings arguments:
   --protect-branches                # Protect branches with default master/main, develop and staging
-  --protect-tags LEVEL              # Protect tags at level [no-one,admins,maintainers,developers]
+  --protect-tags [LEVEL]            # Protect tags at level [no-one,admins,maintainers,developers] (default: no-one)
 
 positional arguments:
   --                                # Positional arguments separator (recommended)
@@ -138,10 +162,20 @@ gitlab-projects-settings --settings
 
 ---
 
+## Environment available configurations
+
+`gitlab-projects-settings` uses `colored` for colors outputs and `questionary` for interactive menus.
+
+If colors of both outputs types do not match the terminal's theme,  
+an environment variable `NO_COLOR=1` can be defined to disable colors.
+
+---
+
 ## Dependencies
 
 - [colored](https://pypi.org/project/colored/): Terminal colors and styles
 - [python-gitlab](https://pypi.org/project/python-gitlab/): A python wrapper for the GitLab API
+- [questionary](https://pypi.org/project/questionary/): Interactive terminal user interfaces
 - [setuptools](https://pypi.org/project/setuptools/): Build and manage Python packages
 - [update-checker](https://pypi.org/project/update-checker/): Check for package updates on PyPI
 

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/gitlab_projects_settings.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ src/package/version.py
 src/prints/__init__.py
 src/prints/boxes.py
 src/prints/colors.py
+src/prints/themes.py
 src/system/__init__.py
 src/system/platform.py
 src/types/__init__.py

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/gitlab_projects_settings.egg-info/requires.txt

@@ -1,4 +1,5 @@
 colored>=1.4.2
 python-gitlab>=4.4.0
+questionary>=2.0.1
 setuptools>=45.1.0
 update_checker>=0.18.0

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/requirements/runtime.txt

@@ -1,4 +1,5 @@
 colored>=1.4.2
 python-gitlab>=4.4.0
+questionary>=2.0.1
 setuptools>=45.1.0
 update_checker>=0.18.0

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/src/cli/entrypoint.py

@@ -12,10 +12,12 @@ from gitlab.v4.objects import (
     Project as GitLabProject,
     User as GitLabUser,
 )
+import questionary
 
 # Components
 from ..features.gitlab import GitLabFeature
 from ..prints.colors import Colors
+from ..prints.themes import Themes
 from ..system.platform import Platform
 from ..types.namespaces import Namespaces
 
@@ -23,7 +25,7 @@ from ..types.namespaces import Namespaces
 class Entrypoint:
 
     # Enumerations
-    Result = Enum('Result', ['SUCCESS', 'FINALIZE', 'ERROR'])
+    Result = Enum('Result', ['SUCCESS', 'FINALIZE', 'ERROR', 'CRITICAL'])
 
     # CLI, pylint: disable=too-many-branches
     @staticmethod
@@ -173,6 +175,30 @@ class Entrypoint:
         # Result
         return Entrypoint.Result.SUCCESS
 
+    # Confirm
+    @staticmethod
+    def confirm(description: str, text: str = '') -> bool:
+
+        # Header
+        print(
+            f'{Colors.BOLD}   - Delete {description}: Confirm "'
+            f'{Colors.RED}{text}'
+            f'{Colors.BOLD}" deletion:'
+            f'{Colors.RESET}', end='')
+        Platform.flush()
+
+        # Get user configuration
+        answer: bool = questionary.confirm(
+            message='',
+            default=False,
+            qmark='',
+            style=Themes.confirmation_style(),
+            auto_enter=True,
+        ).ask()
+
+        # Result
+        return answer
+
     # Group
     @staticmethod
     def group(
@@ -205,8 +231,17 @@ class Entrypoint:
               f'{Colors.RESET}')
         Platform.flush()
 
-        # Delete group
+        # Delete group after validation
         if options.delete_group:
+            if not Entrypoint.confirm(
+                    group_type,
+                    group.full_path,
+            ):
+                print(' ')
+                Platform.flush()
+                return Entrypoint.Result.SUCCESS
+
+            # Delete group
             gitlab.group_delete(criteria)
             print(f'{Colors.BOLD}   - Delete {group_type}: '
                   f'{Colors.GREEN}Success'
@@ -264,6 +299,11 @@ class Entrypoint:
                   f'{Colors.RESET}')
             Platform.flush()
 
+        # Dump group object
+        if options.dump:
+            print(' ')
+            print(group.to_json())
+
         # Footer
         print(' ')
         Platform.flush()
@@ -289,8 +329,17 @@ class Entrypoint:
               f'{Colors.RESET}')
         Platform.flush()
 
-        # Delete project
+        # Delete project after validation
         if options.delete_project:
+            if not Entrypoint.confirm(
+                    'project',
+                    project.path_with_namespace,
+            ):
+                print(' ')
+                Platform.flush()
+                return Entrypoint.Result.SUCCESS
+
+            # Delete project
             gitlab.project_delete(criteria)
             print(f'{Colors.BOLD}   - Delete project: '
                   f'{Colors.GREEN}Success'
@@ -457,6 +506,11 @@ class Entrypoint:
                       f'{Colors.RESET}')
                 Platform.flush()
 
+        # Dump group object
+        if options.dump:
+            print(' ')
+            print(project.to_json())
+
         # Footer
         print(' ')
         Platform.flush()

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/src/cli/main.py

@@ -14,6 +14,7 @@ from ..package.updates import Updates
 from ..package.version import Version
 from ..prints.colors import Colors
 from ..system.platform import Platform
+from ..types.gitlab import ProtectionLevels
 from .entrypoint import Entrypoint
 
 # Main, pylint: disable=too-many-statements
@@ -93,6 +94,12 @@ def main() -> None:
         action='store_true',
         help='Enable dry run mode to check without saving',
     )
+    group.add_argument(
+        '--dump',
+        dest='dump',
+        action='store_true',
+        help='Dump Python objects of groups and projects',
+    )
     group.add_argument(
         '--exclude-group',
         dest='exclude_group',
@@ -216,7 +223,10 @@ def main() -> None:
         dest='protect_tags',
         action='store',
         metavar='LEVEL',
-        help='Protect tags at level [no-one,admins,maintainers,developers]',
+        nargs='?',
+        const=ProtectionLevels.default(),
+        help=f'Protect tags at level [{",".join(ProtectionLevels.names())}]'
+        ' (default: %(const)s)',
     )
 
     # Arguments positional definitions
@@ -232,7 +242,7 @@ def main() -> None:
         action='store',
         nargs='?',
         default='https://gitlab.com',
-        help='GitLab URL (default: https://gitlab.com)',
+        help='GitLab URL (default: %(default)s)',
     )
     group.add_argument(
         dest='path',
@@ -288,18 +298,19 @@ def main() -> None:
 
     # Arguments validation
     if not options.token or not options.gitlab or not options.path:
-        print(' ')
-        parser.print_help()
-        print(' ')
-        Platform.flush()
-        sys_exit(1)
+        result = Entrypoint.Result.CRITICAL
 
     # Header
     print(' ')
     Platform.flush()
 
     # CLI entrypoint
-    result = Entrypoint.cli(options)
+    if result != Entrypoint.Result.CRITICAL:
+        result = Entrypoint.cli(options)
+
+    # CLI helper
+    else:
+        parser.print_help()
 
     # Footer
     print(' ')

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/src/features/gitlab.py

@@ -10,7 +10,7 @@ from gitlab.exceptions import GitlabDeleteError, GitlabGetError, GitlabListError
 from gitlab.v4.objects import Group, Namespace, Project, User
 
 # Components
-from ..types.gitlab import AccessLevels, ProjectFeatures
+from ..types.gitlab import AccessLevels, ProjectFeatures, ProtectionLevels
 
 # GitLabFeature class, pylint: disable=too-many-public-methods
 class GitLabFeature:
@@ -349,13 +349,13 @@ class GitLabFeature:
 
         # Prepare access level
         access_level: int
-        if protect_level == 'no-one':
+        if protect_level == ProtectionLevels.NO_ONE:
             access_level = 0
-        elif protect_level == 'admins':
+        elif protect_level == ProtectionLevels.ADMINS:
             access_level = 60
-        elif protect_level == 'maintainers':
+        elif protect_level == ProtectionLevels.MAINTAINERS:
             access_level = 40
-        elif protect_level == 'developers':
+        elif protect_level == ProtectionLevels.DEVELOPERS:
             access_level = 30
         else:
             raise SyntaxError(f'Unknown protection level: {access_level}')

gitlab_projects_settings-4.2.0/src/prints/themes.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+
+# Modules libraries
+try:
+    from prompt_toolkit.styles.style import Style as prompt_toolkit_styles_Style
+except ModuleNotFoundError: # pragma: no cover
+    from typing import Any as prompt_toolkit_styles_Style # type: ignore[assignment]
+
+# Components
+from .colors import Colors
+
+# Themes class, pylint: disable=too-few-public-methods
+class Themes:
+
+    # Flags
+    __prepared = False
+
+    # Members
+    __bold: str = ''
+    __red: str = ''
+    __selected: str = ''
+
+    # Prepare
+    @staticmethod
+    def __prepare() -> None:
+
+        # Colors enabled
+        if Colors.enabled():
+            Themes.__bold = 'bold'
+            Themes.__red = '#FF0000 bold'
+            Themes.__selected = 'bold noreverse'
+
+        # Colors disabled
+        else:
+            Themes.__bold = 'noinherit bold'
+            Themes.__red = 'noinherit bold'
+            Themes.__selected = 'noinherit bold noreverse'
+
+        # Raise flag
+        Themes.__prepared = True
+
+    # Confirmation
+    @staticmethod
+    def confirmation_style() -> prompt_toolkit_styles_Style:
+
+        # Prepare
+        if not Themes.__prepared:
+            Themes.__prepare()
+
+        # Result
+        return prompt_toolkit_styles_Style([
+            ('answer', Themes.__red),
+            ('instruction', Themes.__red),
+            ('highlighted', Themes.__bold),
+            ('pointer', Themes.__bold),
+            ('qmark', Themes.__bold),
+            ('question', Themes.__bold),
+            ('selected', Themes.__selected),
+            ('separator', Themes.__bold),
+        ])

{gitlab_projects_settings-4.0.0 → gitlab_projects_settings-4.2.0}/src/types/gitlab.py

@@ -14,6 +14,28 @@ class AccessLevels:
     PRIVATE: str = 'private'
     ENABLED: str = 'enabled'
 
+# ProtectionLevels class
+class ProtectionLevels:
+    NO_ONE: str = 'no-one'
+    ADMINS: str = 'admins'
+    MAINTAINERS: str = 'maintainers'
+    DEVELOPERS: str = 'developers'
+
+    # Default
+    @staticmethod
+    def default() -> str:
+        return ProtectionLevels.NO_ONE
+
+    # Names
+    @staticmethod
+    def names() -> List[str]:
+        return [
+            ProtectionLevels.NO_ONE,
+            ProtectionLevels.ADMINS,
+            ProtectionLevels.MAINTAINERS,
+            ProtectionLevels.DEVELOPERS,
+        ]
+
 # Visibility class, pylint: disable=too-few-public-methods
 class Visibility:
     PRIVATE: str = 'private'