glpkg 0.0.1__py3-none-any.whl

gitlab/__init__.py

@@ -0,0 +1,3 @@
+from gitlab.packages import Packages
+
+__version__ = "0.0.1"

gitlab/__main__.py

@@ -0,0 +1,12 @@
+import sys
+
+from gitlab.cli_handler import CLIHandler
+
+
+def cli() -> int:
+    handler = CLIHandler()
+    return handler.do_it()
+
+
+if __name__ == "__main__":
+    sys.exit(cli())

gitlab/cli_handler.py

@@ -0,0 +1,134 @@
+import argparse
+import os
+from gitlab import Packages, __version__
+
+
+class CLIHandler:
+    def __init__(self):
+        parser = argparse.ArgumentParser(
+            description="Toolbox for GitLab generic packages"
+        )
+        parser.add_argument("-v", "--version", action="store_true")
+        parser.set_defaults(action=self._print_version)
+        subparsers = parser.add_subparsers()
+        list_parser = subparsers.add_parser(
+            name="list",
+            description="Lists the available version of a package from the package registry.",
+        )
+        self._register_list_parser(list_parser)
+        download_parser = subparsers.add_parser(
+            name="download",
+            description="Downloads all files from a specific package version to the current directory.",
+        )
+        self._register_download_parser(download_parser)
+        upload_parser = subparsers.add_parser(
+            name="upload", description="Uploads file to a specific package version."
+        )
+        self._register_upload_parser(upload_parser)
+        self.args = parser.parse_args()
+
+    def _print_version(self, args) -> int:
+        print(__version__)
+        return 0
+
+    def do_it(self) -> int:
+        return self.args.action(self.args)
+
+    def _register_common_arguments(self, parser) -> None:
+        group = parser.add_mutually_exclusive_group()
+        group.add_argument(
+            "-H",
+            "--host",
+            default="gitlab.com",
+            type=str,
+            help="The host address of GitLab instance without scheme, for example gitlab.com. Note that only https scheme is supported.",
+        )
+        group.add_argument(
+            "-c",
+            "--ci",
+            action="store_true",
+            help="Use this to run the tool in GitLab pipelines. In this case CI_SERVER_HOST, CI_PROJECT_ID, and CI_JOB_TOKEN variables from the environment are used. --project and --token can be used to override project ID and the CI_JOB_TOKEN to a personal or project access token.",
+        )
+        parser.add_argument(
+            "-p",
+            "--project",
+            type=str,
+            help="The project ID or path. For example 123456 or namespace/project.",
+        )
+        parser.add_argument("-n", "--name", type=str, help="The package name.")
+        parser.add_argument(
+            "-t",
+            "--token",
+            type=str,
+            help="Private or project access token that is used to authenticate with the package registry. Leave empty if the registry is public. The token must have 'read API' or 'API' scope.",
+        )
+
+    def _register_download_parser(self, parser):
+        self._register_common_arguments(parser)
+        parser.add_argument("-v", "--version", type=str, help="The package version.")
+        parser.set_defaults(action=self._download_handler)
+
+    def _args(self, args):
+        if args.ci:
+            host = os.environ["CI_SERVER_HOST"]
+            if args.project:
+                project = args.project
+            else:
+                project = os.environ["CI_PROJECT_ID"]
+            if args.token:
+                token_user = "PRIVATE-TOKEN"
+                token = args.token
+            else:
+                token_user = "JOB-TOKEN"
+                token = os.environ["CI_JOB_TOKEN"]
+        else:
+            host = args.host
+            project = args.project
+            token_user = "PRIVATE-TOKEN"
+            token = args.token
+        name = args.name
+        return host, project, name, token_user, token
+
+    def _download_handler(self, args) -> int:
+        host, project, name, token_user, token = self._args(args)
+        version = args.version
+        gitlab = Packages(host, token_user, token)
+        package_id = gitlab.get_package_id(project, name, version)
+        files = gitlab.list_files(project, package_id)
+        ret = 1
+        for file in files:
+            ret = gitlab.download_file(project, name, version, file)
+            if not ret:
+                break
+        return ret
+
+    def _register_list_parser(self, parser):
+        self._register_common_arguments(parser)
+        parser.set_defaults(action=self._list_packages)
+
+    def _list_packages(self, args: argparse.Namespace) -> int:
+        host, project, name, token_user, token = self._args(args)
+        gitlab = Packages(host, token_user, token)
+        packages = gitlab.list_packages(project, name)
+        print("Name" + "\t\t" + "Version")
+        for package in packages:
+            print(package["name"] + "\t" + package["version"])
+
+    def _register_upload_parser(self, parser):
+        self._register_common_arguments(parser)
+        parser.add_argument("-v", "--version", type=str, help="The package version.")
+        parser.add_argument(
+            "-f",
+            "--file",
+            type=str,
+            help="The file to be uploaded, for example my_file.txt. Note that only relative paths are supported and the relative path is preserved when uploading the file.",
+        )
+        parser.set_defaults(action=self._upload)
+
+    def _upload(self, args) -> int:
+        host, project, name, token_user, token = self._args(args)
+        version = args.version
+        file = args.file
+        gitlab = Packages(host, token_user, token)
+        ret = gitlab.upload_file(project, name, version, file)
+        return ret

gitlab/packages.py

@@ -0,0 +1,130 @@
+import json
+from urllib import request, parse
+
+
+class Packages:
+    def __init__(self, host: str, token_type: str, token: str):
+        self.host = host
+        self.token_type = token_type
+        self.token = token
+
+    def api_url(self) -> str:
+        return "https://{}/api/v4/".format(parse.quote(self.host))
+
+    def project_api_url(self, project: str) -> str:
+        return self.api_url() + "projects/{}/".format(parse.quote_plus(project))
+
+    def get_headers(self):
+        headers = {}
+        if self.token_type and self.token:
+            headers = {self.token_type: self.token}
+        return headers
+
+    def list_packages(self, project: str, package_name: str) -> list:
+        packages = []
+        with request.urlopen(
+            request.Request(
+                self.project_api_url(project)
+                + "packages?package_name="
+                + parse.quote_plus(package_name),
+                headers=self.get_headers(),
+            )
+        ) as res:
+            data = res.read()
+            for package in json.loads(data):
+                name = parse.unquote(package["name"])
+                version = parse.unquote(package["version"])
+                # The GitLab API returns packages that have some match to the filter;
+                # let's filter out non-exact matches
+                if package_name != name:
+                    continue
+                packages.append({"name": name, "version": version})
+        return packages
+
+    def list_files(self, project: str, package_id: int) -> list:
+        files = []
+        with request.urlopen(
+            request.Request(
+                self.project_api_url(project)
+                + "packages/"
+                + parse.quote_plus(str(package_id))
+                + "/package_files",
+                headers=self.get_headers(),
+            )
+        ) as x:
+            data = x.read()
+            for package in json.loads(
+                data,
+            ):
+                # Only append the filename once to the list of files
+                # as there's no way to download them separately through
+                # the API
+                filename = parse.unquote(package["file_name"])
+                if filename not in files:
+                    files.append(filename)
+        return files
+
+    def get_package_id(
+        self, project: str, package_name: str, package_version: str
+    ) -> int:
+        id = 0
+        with request.urlopen(
+            request.Request(
+                self.project_api_url(project)
+                + "packages?package_name="
+                + parse.quote_plus(package_name)
+                + "&package_version="
+                + parse.quote_plus(package_version),
+                headers=self.get_headers(),
+            )
+        ) as res:
+            data = res.read()
+            package = json.loads(data)
+            if len(package) == 1:
+                package = package.pop()
+                id = package["id"]
+        return id
+
+    def download_file(
+        self, project: str, package_name: str, package_version: str, file: str
+    ) -> int:
+        ret = 1
+        with request.urlopen(
+            request.Request(
+                self.project_api_url(project)
+                + "packages/generic/"
+                + parse.quote_plus(package_name)
+                + "/"
+                + parse.quote_plus(package_version)
+                + "/"
+                + parse.quote(str(file)),
+                headers=self.get_headers(),
+            )
+        ) as req:
+            with open(str(file), "wb") as file:
+                file.write(req.read())
+                ret = 0
+        return ret
+
+    def upload_file(
+        self, project: str, package_name: str, package_version: str, file: str
+    ) -> int:
+        ret = 1
+        with open(str(file), "rb") as data:
+            res = request.urlopen(
+                request.Request(
+                    self.project_api_url(project)
+                    + "packages/generic/"
+                    + parse.quote_plus(package_name)
+                    + "/"
+                    + parse.quote_plus(package_version)
+                    + "/"
+                    + parse.quote(str(file)),
+                    method="PUT",
+                    data=data,
+                    headers=self.get_headers(),
+                )
+            )
+            if res.getcode() == 201:  # 201 is created
+                ret = 0
+        return ret

glpkg-0.0.1.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: glpkg
+Version: 0.0.1
+Summary: Tool to make GitLab generic package registry operations easy.
+Author-email: bugproduction <bugproduction@outlook.com>
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.com/bugproduction/glpkg.git
+Keywords: GitLab,packages,registry,generic
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# glpkg - GitLab Generic Package registry tools 
+
+glpkg is a tool that makes it easy to work with [GitLab generic package registry](https://docs.gitlab.com/user/packages/generic_packages/).
+
+
+## Installation
+
+Install the tool from with pip:
+
+```bash
+pip install glpkg
+```
+
+To check the installation and version,  run:
+
+
+```bash
+glpkg --version
+```
+
+If you see a version in the terminal, you're good to go!
+
+## Usage
+
+By default, the used GitLab host is gitlab.com. If you use a self-hosted GitLab, use argument `--host my-gitlab.net` with the commands.
+
+> Only https scheme is supported.
+
+To authenticate with the package registry in any of the commands below, use `--token readapitoken123` argument where the `readapitoken123` is a [personal](https://docs.gitlab.com/user/profile/personal_access_tokens/#create-a-personal-access-token) or [project](https://docs.gitlab.com/user/project/settings/project_access_tokens/#create-a-project-access-token) access token, with read API scope. In case the package registry is public, you can omit this argument.
+
+The above arguments are omitted in the examples below to focus on the functions. Add the arguments to change the host or to authenticate with the registry.
+
+In general, run `glpkg --help` when needed.
+
+### Listing package versions
+
+To list the versions of a generic package, run
+
+```bash
+glpkg list --project 12345 --name mypackagename
+```
+
+Where:
+- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#find-the-project-id)) or the path of the project (like `namespace/project`)
+- `mypackagename` is the name of the generic package
+
+The output will be, if package is found, something like:
+
+```bash
+Name            Version
+mypackagename   1.0
+mypackagename   1.5
+mypackagename   2.0
+```
+
+### Download generic package
+
+To download everything from a specific generic package, run
+
+```bash
+glpkg download --project 12345 --name mypackagename --version 1.0
+```
+
+Where:
+- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#find-the-project-id)) or the path of the project (like `namespace/project`)
+- `mypackagename` is the name of the generic package
+- `1.0` is the version of the generic package from which the files are downloaded
+
+The files will be downloaded in the current working directory. Any pre-existing files will be overridden without warning.
+
+> If a package has multiple files with the same filename, the tool can only download the newest file. This is a restriction of GitLab API.
+
+### Upload a file to a generic package
+
+To upload a file to a version of a generic package, run
+
+```bash
+glpkg upload --project 12345 --name mypackagename --version 1.0 --file my-file.txt
+```
+
+Where:
+- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#find-the-project-id)) or the path of the project (like `namespace/project`)
+- `mypackagename` is the name of the generic package
+- `1.0` is the version of the generic package to which the file is uploaded
+- `my-file.txt` is the file that is uploaded to the generic package. Currently, only relative paths are supported, and the relative path (e.g. `folder/file.txt`) is preserved when uploading the file to the registry.
+
+> A GitLab generic package may have multiple files with the same file name. However, it likely is not a great idea, as they cannot be downloaded separately from the GitLab API.
+
+### Use in GitLab pipelines
+
+If you use the tool in a GitLab pipeline, using `--ci` argument uses [GitLab predefined variables](https://docs.gitlab.com/ci/variables/predefined_variables/) to configure the tool. In this case `CI_SERVER_HOST`, `CI_PROJECT_ID`, and `CI_JOB_TOKEN` environment variables are used. The `--project`, and `--token` arguments can still be used to override the project ID and to use a personal or project access token instead of CI_JOB_TOKEN.
+
+In other words, you don't need to give the `--host`, `--project`, or `--token` arguments if you are interacting with the package registry of the project where the pipeline is running. Example: uploading `my-file.txt` to generic package `mypackagename` version `1.0` in the project package registry in CI:
+
+```bash
+glpkg upload --ci --name mypackagename --version 1.0 --file my-file.txt
+```
+
+To use the `CI_JOB_TOKEN` with package registry of another projects, add `--project <otherproject ID>` argument. Remember that you may need to add [permissions for the CI_JOB_TOKEN](https://docs.gitlab.com/ci/jobs/ci_job_token/#control-job-token-access-to-your-project) in the other project.
+
+
+## Limitations
+
+The tool is not perfect (yet) and has limitations. The following limitations are known, but more can exist:
+
+- Uploading files must be done one-by-one.
+- Only project registries are supported for now.
+- Pagination is not supported for now - in case you have more than 100 versions of a package, not all will be shown.

glpkg-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+gitlab/__init__.py,sha256=xA73jnLd2tGhd-9FwN86PRC0GscMytsHi3Sa6W-_WMk,60
+gitlab/__main__.py,sha256=88VNY5Qrmn8g0rNcnjKNdN746--0chHsKBMH3PD3Nao,177
+gitlab/cli_handler.py,sha256=kbbKMAxdTqeso_xSO5ZwmXI9ppGt0mABlxlqifkmaaM,5346
+gitlab/packages.py,sha256=Aw2Zt3Ok1uA9K8p8kugP3vizvcAxFMDaTQTwC-HH_sI,4431
+glpkg-0.0.1.dist-info/licenses/LICENSE.md,sha256=josGXvZq628dNS0Iru58-DPE7dRpDXzjJxKKT35103g,1065
+glpkg-0.0.1.dist-info/METADATA,sha256=IbfrEJtkS8OLW0W1VrfHnOlB8bdtpvGsUXSaun4YEOY,5617
+glpkg-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+glpkg-0.0.1.dist-info/entry_points.txt,sha256=xHPZwx2oShYDZ3AyH7WSIvuhFMssy7QLlQk-JAbje_w,46
+glpkg-0.0.1.dist-info/top_level.txt,sha256=MvIaP8p_Oaf4gO_hXmHkX-5y2deHLp1pe6tJR3ukQ6o,7
+glpkg-0.0.1.dist-info/RECORD,,

glpkg-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

glpkg-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+glpkg = gitlab.__main__:cli

glpkg-0.0.1.dist-info/licenses/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2025 bugproduction
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

glpkg-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+gitlab