glpkg 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

gitlab/__init__.py

@@ -1,3 +1,5 @@
+"""GitLab packages initialization module"""
+
 from gitlab.packages import Packages
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"

gitlab/__main__.py

@@ -1,9 +1,26 @@
+"""GitLab packages main module"""
+
+import logging
 import sys
 
 from gitlab.cli_handler import CLIHandler
 
 
 def cli() -> int:
+    """
+    Runs the main program of the glpkg.
+
+    Uses arguments from command line and executes the given command.
+
+    Return
+    ------
+    int
+        Zero when everything is fine, non-zero otherwise.
+    """
+    logging.basicConfig(
+        level=logging.DEBUG,
+        handlers=[logging.FileHandler("glpkg.log")],  # , logging.StreamHandler()],
+    )
     handler = CLIHandler()
     return handler.do_it()
 

gitlab/cli_handler.py

@@ -1,11 +1,23 @@
+"""CLI handler for glpkg"""
+
 import argparse
-import netrc
+from netrc import netrc
 import os
+import sys
+import urllib
 from gitlab import Packages, __version__
 
 
 class CLIHandler:
+    """Class to parse CLI arguments and run the requested command"""
+
     def __init__(self):
+        """
+        Creates a new instance of CLIHandler.
+
+        Parses the arguments from command line and prepares everything
+        to be ready to executed. Just use do_it to run it!
+        """
         parser = argparse.ArgumentParser(
             description="Toolbox for GitLab generic packages"
         )
@@ -14,12 +26,14 @@ class CLIHandler:
         subparsers = parser.add_subparsers()
         list_parser = subparsers.add_parser(
             name="list",
-            description="Lists the available version of a package from the package registry.",
+            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.",
+            description="Downloads all files from a specific package version "
+            "to the current directory.",
         )
         self._register_download_parser(download_parser)
         upload_parser = subparsers.add_parser(
@@ -28,27 +42,81 @@ class CLIHandler:
         self._register_upload_parser(upload_parser)
         self.args = parser.parse_args()
 
-    def _print_version(self, args) -> int:
+    def _print_version(self, _args: argparse.Namespace) -> int:
+        """
+        A handler for printing the version of the tool to the console.
+
+        Parameters
+        ----------
+        _args : argparse.Namespace
+            Unused.
+
+        Return
+        ------
+        int
+            Zero when printing to console succeeded.
+        """
         print(__version__)
         return 0
 
     def do_it(self) -> int:
-        return self.args.action(self.args)
+        """
+        Executes the requested command.
+
+        In case of error, prints to stderr.
+
+        Return
+        ------
+        int
+            Zero when everything went fine, non-zero otherwise.
+        """
+        ret = 1
+        try:
+            ret = self.args.action(self.args)
+        except urllib.error.HTTPError as e:
+            # GitLab API returns 404 when a resource is not found
+            # but also when the user has no access to the resource
+            print("Oops! Something did go wrong.", file=sys.stderr)
+            print(e, file=sys.stderr)
+            print(
+                "Note that Error 404 may also indicate authentication issues with GitLab API.",
+                file=sys.stderr,
+            )
+            print("Check your arguments and credentials.", file=sys.stderr)
+        return ret
+
+    def _register_common_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """
+        Registers common arguments to the parser:
+            - host
+            - ci
+            - project
+            - name
+            - token
+            - netrc
 
-    def _register_common_arguments(self, parser) -> None:
+        Parameters
+        ----------
+        parser:
+            The argparser where to register the common arguments.
+        """
         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.",
+            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 in GitLab jobs. 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.",
+            help="Use this in GitLab jobs. 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",
@@ -62,20 +130,77 @@ class CLIHandler:
             "-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.",
+            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.",
         )
         group2.add_argument(
             "--netrc",
             action="store_true",
-            help="Set to use a token from .netrc file (~/.netrc) for the host. The .netrc username is ignored due to API restrictions. PRIVATE-TOKEN is used instead. Note that .netrc file access rights must be correct.",
+            help="Set to use a token from .netrc file (~/.netrc) for the host. The "
+            ".netrc username is ignored due to API restrictions. PRIVATE-TOKEN is used "
+            "instead. Note that .netrc file access rights must be correct.",
         )
 
-    def _register_download_parser(self, parser):
+    def _register_download_parser(self, parser: argparse.ArgumentParser):
+        """
+        Registers the download command related arguments to the parser:
+            - version
+            - file
+            - destination
+            - action
+
+        Additionally, registers the common args.
+
+        Parameters
+        ----------
+        parser:
+            The argparser where to register the download arguments.
+        """
         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 download from the package. If not defined, all "
+            "files are downloaded.",
+        )
+        parser.add_argument(
+            "-d",
+            "--destination",
+            default="",
+            type=str,
+            help="The path where the file(s) are downloaded. If not defined, "
+            "the current working directory is used.",
+        )
         parser.set_defaults(action=self._download_handler)
 
-    def _args(self, args):
+    def _args(self, args) -> tuple[str, str, str, str, str]:
+        """
+        Returns the connection parameters according to the args
+
+        Parameters
+        ----------
+        args:
+            The args that are used to determined the connection parameters
+
+        Returns
+        -------
+        host : str
+            The GitLab host name
+        project : str
+            The Project ID or name to use
+        name : str
+            The package name
+        token_user : str
+            The token user according to the args. If ci is used, returns `JOB-TOKEN`, else
+            `PRIVATE-TOKEN`.
+        token : str
+            The token according to the args. If token is set, returns it. If netrc is set,
+            reads the token from the .netrc file. If ci is set, reads the environment
+            variable CI_JOB_TOKEN. Otherwise returns None.
+        """
         if args.ci:
             host = os.environ["CI_SERVER_HOST"]
             project = os.environ["CI_PROJECT_ID"]
@@ -92,21 +217,39 @@ class CLIHandler:
             token = args.token
             token_user = "PRIVATE-TOKEN"
         if args.netrc:
-            _, _, token = netrc.netrc().authenticators(host)
+            _, _, token = netrc().authenticators(host)
             token_user = "PRIVATE-TOKEN"
         name = args.name
         return host, project, name, token_user, token
 
-    def _download_handler(self, args) -> int:
+    def _download_handler(self, args: argparse.Namespace) -> int:
+        """
+        Downloads package file(s) from GitLab package registry.
+
+        Parameters
+        ----------
+        args : argparse.Namespace
+            The parsed arguments
+
+        Returns
+        -------
+        int
+            Zero if everything goes well, non-zero otherwise
+        """
         ret = 1
         host, project, name, token_user, token = self._args(args)
         version = args.version
+        destination = args.destination
         gitlab = Packages(host, token_user, token)
         package_id = gitlab.get_package_id(project, name, version)
         if package_id:
-            files = gitlab.list_files(project, package_id)
+            files = []
+            if args.file:
+                files.append(args.file)
+            else:
+                files = gitlab.list_files(project, package_id)
             for file in files:
-                ret = gitlab.download_file(project, name, version, file)
+                ret = gitlab.download_file(project, name, version, file, destination)
                 if ret:
                     print("Failed to download file " + file)
                     break
@@ -114,11 +257,35 @@ class CLIHandler:
             print("No package " + name + " version " + version + " found!")
         return ret
 
-    def _register_list_parser(self, parser):
+    def _register_list_parser(self, parser: argparse.ArgumentParser):
+        """
+        Registers the list command related arguments to the parser:
+            - action
+
+        Additionally, registers the common args.
+
+        Parameters
+        ----------
+        parser:
+            The argparser where to register the list arguments.
+        """
         self._register_common_arguments(parser)
         parser.set_defaults(action=self._list_packages)
 
     def _list_packages(self, args: argparse.Namespace) -> int:
+        """
+        List package versions from GitLab package registry.
+
+        Parameters
+        ----------
+        args : argparse.Namespace
+            The parsed arguments
+
+        Returns
+        -------
+        int
+            Zero if everything goes well, non-zero otherwise
+        """
         host, project, name, token_user, token = self._args(args)
         gitlab = Packages(host, token_user, token)
         packages = gitlab.list_packages(project, name)
@@ -126,25 +293,69 @@ class CLIHandler:
         for package in packages:
             print(package["name"] + "\t" + package["version"])
 
-    def _register_upload_parser(self, parser):
+    def _register_upload_parser(self, parser: argparse.ArgumentParser):
+        """
+        Registers the upload command related arguments to the parser:
+            - version
+            - file
+            - action
+
+        Additionally, registers the common args.
+
+        Parameters
+        ----------
+        parser:
+            The argparser where to register the upload arguments.
+        """
         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.",
+            help="The file to be uploaded, for example my_file.txt. Note that "
+            "only relative paths (to the source) are supported and the relative "
+            "path is preserved when uploading the file. If left undefined, all files "
+            "of the source directory are uploaded. For example --source=temp --file=myfile "
+            "will upload myfile to the GitLab generic package root. However using --source=. "
+            "(or omittinge source) --file=temp/myfile will upload the file to temp folder "
+            "in the GitLab package.",
+        )
+        parser.add_argument(
+            "-s",
+            "--source",
+            type=str,
+            default="",
+            help="The source directory of the uploaded file(s). Defaults to current"
+            "working directory.",
         )
         parser.set_defaults(action=self._upload)
 
-    def _upload(self, args) -> int:
-        ret = 1
+    def _upload(self, args: argparse.Namespace) -> int:
+        """
+        Uploads a file to a GitLab package registry
+
+        Parameters
+        ----------
+        args : argparse.Namespace
+            The arguments from command line
+
+        Returns
+        -------
+        int
+            Zero if everything went fine, non-zero otherwise.
+        """
+        ret = 0
         host, project, name, token_user, token = self._args(args)
         version = args.version
         file = args.file
-        if os.path.isfile(file):
+        source = args.source
+        if file:
+            # Check if the uploaded file exists.
+            if not os.path.isfile(os.path.join(source, file)):
+                print("File " + file + " does not exist!")
+                ret = 1
+        if not ret:
             gitlab = Packages(host, token_user, token)
-            ret = gitlab.upload_file(project, name, version, file)
-        else:
-            print("File " + file + " does not exist!")
+            ret = gitlab.upload_file(project, name, version, file, source)
         return ret

gitlab/packages.py

@@ -1,66 +1,199 @@
+"""GitLab generic packages module"""
+
+from glob import glob
 from http.client import HTTPMessage
-import json
+from json import loads
 import logging
+import os
 from urllib import request, parse
 
 logger = logging.getLogger(__name__)
 
 
 class Packages:
+    """Class to interact with GitLab packages REST API"""
+
     def __init__(self, host: str, token_type: str, token: str):
+        """
+        Creates a new instance of Packages class.
+
+        Parameters
+        ----------
+        host : str
+            The GitLab instance hostname, without schema.
+            The host will be used for the package API interaction.
+            For example gitlab.com.
+        token_type : str
+            The token type or "user" to authenticate with GitLab REST API.
+            For personal, project, and group tokens this is `PRIVATE-TOKEN`.
+            For `CI_JOB_TOKEN` this is `JOB-TOKEN`.
+            Can be left empty when authentication is not used.
+        token : str
+            The token (secret) to authenticate with GitLab REST API.
+            This can be a personal token, project token, or`CI_JOB_TOKEN`.
+            Leave empty when authentication is not used.
+        """
         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))
+        """
+        Returns the GitLab REST API URL by using the host variable.
+
+        Returns
+        -------
+        str
+            The GitLab REST API URL, for example `https://gitlab.com/api/v4/`.
+        """
+        return f"https://{self.host}/api/v4/"
 
     def project_api_url(self, project: str) -> str:
-        return self.api_url() + "projects/{}/".format(parse.quote_plus(project))
+        """
+        Returns the project REST API URL of the project
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+
+        Returns
+        -------
+        str
+            The project REST API URL, for example `https://gitlab.com/api/v4/projects/123/`
+            or `https://gitlab.com/api/v4/projects/namespace%2Fproject/`
+        """
+        return f"{self.api_url()}projects/{parse.quote_plus(project)}/"
 
     def get_headers(self) -> dict:
+        """
+        Creates headers for a GitLab REST API call.
+
+        The headers contain token for authentication according to the
+        instance variables.
+
+        Returns
+        -------
+        dict
+            Headers for a REST API request, that contain the authentication token.
+        """
         headers = {}
         if self.token_type and self.token:
             headers = {self.token_type: self.token}
         return headers
 
     def _request(self, url: str) -> tuple[int, bytes, HTTPMessage]:
-        logger.debug("Requesting " + url)
+        """
+        Makes a HTTP request to the given URL, and returns
+        the response status, body, and headers.
+
+
+        Parameters
+        ----------
+        url : str
+            The URL of the HTTP request to make.
+
+        Returns
+        -------
+        int
+            The HTTP response code, such as 200
+        bytes
+            The HTTP response body read as bytes
+        HTTPMessage
+            The HTTP response headers
+        """
+        logger.debug("Requesting %s", url)
         req = request.Request(url, headers=self.get_headers())
         with request.urlopen(req) as response:
             return response.status, response.read(), response.headers
 
     def _get_next_page(self, headers: HTTPMessage) -> int:
+        """
+        Returns the next page from headers for pagination.
+
+        Uses the field x-next-page from the headers.
+
+        Parameters
+        ----------
+        headers : HTTPMessage
+            The header from which to get the next page number for
+            pagination
+
+        Returns
+        -------
+        int
+            The next page number. If headers were empty or they
+            did not include suitable item, returns 0. In such
+            case, do not attempt to fetch a next page.
+        """
         ret = 0
         if headers:
             next_page = headers.get("x-next-page")
             if next_page:
                 ret = int(next_page)
-                logger.debug("Response incomplete, next page is " + next_page)
+                logger.debug("Response incomplete, next page is %s", next_page)
             else:
                 logger.debug("Response complete")
         return ret
 
     def _build_query(self, arg: str, page: int) -> str:
+        """
+        Builds a query for a GitLab REST API request
+
+        Parameters
+        ----------
+        arg : str
+            The args of the query that is endpoint specific
+        page : int
+            Page number for the pagination of the request.
+            Set to 0 to omit the pagination.
+
+        Returns
+        -------
+        str
+            A query string for a REST API request. Append this to
+            the request URL. Example `?arg=this&page=3`.
+        """
         query = ""
         if arg or page:
             if page:
                 page = "page=" + str(page)
-            query = "?{}".format("&".join(filter(None, (arg, page))))
+            query = f"?{'&'.join(filter(None, (arg, page)))}"
         return query
 
-    def gl_project_api(self, project: str, path: str, arg: str = None) -> list:
+    def gl_project_api(self, project: str, apath: str, arg: str = None) -> list:
+        """
+        Returns data from the project REST API for the path. In case
+        of multiple pages, all data will be returned.
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+        apath : str
+            The path of the project API endpoint that is called. For example packages
+        arg : str, optional
+            Additional arguments for the query of the URL, for example to filter
+            results: package_name=mypackage
+
+        Returns
+        -------
+        list
+            Data from GitLab REST API endpoint with the arguments.
+        """
         data = []
         more = True
         page = None
         while more:
             more = False
             query = self._build_query(arg, page)
-            url = self.project_api_url(project) + path + query
+            url = self.project_api_url(project) + apath + query
             status, res_data, headers = self._request(url)
-            logger.debug("Response status: " + str(status))
-            res_data = json.loads(res_data)
-            logger.debug("Response data: " + str(res_data))
+            logger.debug("Response status: %d", status)
+            res_data = loads(res_data)
+            logger.debug("Response data: %s", res_data)
             data = data + res_data
             page = self._get_next_page(headers)
             if page:
@@ -68,8 +201,24 @@ class Packages:
         return data
 
     def list_packages(self, project: str, package_name: str) -> list:
+        """
+        Lists the available versions of the package
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+        package_name : str
+            The name of the package that is listed.
+
+        Returns
+        -------
+        list
+            List of {package: name, version: version} that are available.
+        """
         packages = []
-        logger.debug("Listing packages with name " + package_name)
+        logger.debug("Listing packages with name %s", package_name)
         data = self.gl_project_api(
             project, "packages", "package_name=" + parse.quote_plus(package_name)
         )
@@ -84,10 +233,26 @@ class Packages:
         return packages
 
     def list_files(self, project: str, package_id: int) -> list:
+        """
+        Lists all files of a specific package ID from GitLab REST API
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+        package_id : int
+            The package ID that is listed
+
+        Return
+        ------
+        list
+            List of file (names) that are in the package.
+        """
         files = []
-        logger.debug("Listing package " + str(package_id) + " files")
-        path = "packages/" + parse.quote_plus(str(package_id)) + "/package_files"
-        data = self.gl_project_api(project, path)
+        logger.debug("Listing package %d files", package_id)
+        apath = "packages/" + parse.quote_plus(str(package_id)) + "/package_files"
+        data = self.gl_project_api(project, apath)
         for package in data:
             # Only append the filename once to the list of files
             # as there's no way to download them separately through
@@ -100,28 +265,72 @@ class Packages:
     def get_package_id(
         self, project: str, package_name: str, package_version: str
     ) -> int:
-        id = 0
-        logger.debug(
-            "Fetching package " + package_name + " (" + package_version + ") ID"
-        )
-        path = "packages"
+        """
+        Gets the package ID of a specific package version.
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+        package_name : str
+            The name of the package.
+        package_version : str
+            The version of the package
+
+        Return
+        ------
+        int
+            The ID of the package. Zero if no ID was found.
+        """
+        package_id = 0
+        logger.debug("Fetching package %s (%s) ID", package_name, package_version)
+        apath = "packages"
         arg = (
             "package_name="
             + parse.quote_plus(package_name)
             + "&package_version="
             + parse.quote_plus(package_version)
         )
-        data = self.gl_project_api(project, path, arg)
+        data = self.gl_project_api(project, apath, arg)
         if len(data) == 1:
             package = data.pop()
-            id = package["id"]
-        return id
+            package_id = package["id"]
+        return package_id
 
     def download_file(
-        self, project: str, package_name: str, package_version: str, file: str
+        self,
+        project: str,
+        package_name: str,
+        package_version: str,
+        filename: str,
+        destination: str = "",
     ) -> int:
+        """
+        Downloads a file from a GitLab generic package
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+        package_name : str
+            The name of the generic package.
+        package_version : str
+            The version of the generic package
+        filename : str
+            The file that is downloaded
+        destination : str, optional
+            The destination folder of the downloaded file. If not set,
+            current working directory is used.
+
+        Return
+        ------
+        int
+            Zero if everything went fine, non-zero coke otherwise.
+        """
         ret = 1
-        logger.debug("Downloading file " + file)
+        logger.debug("Downloading file %s", filename)
         url = (
             self.project_api_url(project)
             + "packages/generic/"
@@ -129,21 +338,107 @@ class Packages:
             + "/"
             + parse.quote_plus(package_version)
             + "/"
-            + parse.quote(str(file))
+            + parse.quote(filename)
         )
         status, data, _ = self._request(url)
         if status == 200:
-            with open(str(file), "wb") as file:
+            fpath = os.path.join(destination, filename)
+            parent = os.path.dirname(fpath)
+            if parent:
+                # Create missing directories if needed
+                # In case path has no parent, current
+                # workind directory is used
+                os.makedirs(os.path.dirname(fpath), exist_ok=True)
+            with open(fpath, "wb") as file:
                 file.write(data)
                 ret = 0
         return ret
 
     def upload_file(
-        self, project: str, package_name: str, package_version: str, file: str
+        self,
+        project: str,
+        package_name: str,
+        package_version: str,
+        pfile: str,
+        source: str,
     ) -> int:
+        """
+        Uploads file(s) to a GitLab generic package.
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+        package_name : str
+            The name of the generic package.
+        package_version : str
+            The version of the generic package
+        file : str
+            The relative path of the file that is uploaded. If left empty,
+            all files from the source folder, and it's subfolders, are uploaded.
+        source : str
+            The source folder that is used as root when uploading. If empty,
+            current working directory is used.
+
+        Return
+        ------
+        int
+            Zero if everything went fine, non-zero coke otherwise.
+        """
+        files = []
         ret = 1
-        logger.debug("Uploading file " + file)
-        with open(str(file), "rb") as data:
+        if pfile:
+            files.append(pfile)
+        else:
+            filelist = glob(os.path.join(source, "**"), recursive=True)
+            for item in filelist:
+                # Only add files, not folders
+                if os.path.isfile(os.path.join(item)):
+                    # Remove the source folder from the path of the files
+                    files.append(os.path.relpath(item, source))
+        for ufile in files:
+            ret = self._upload_file(
+                project, package_name, package_version, ufile, source
+            )
+            if ret:
+                break
+        return ret
+
+    def _upload_file(
+        self,
+        project: str,
+        package_name: str,
+        package_version: str,
+        pfile: str,
+        source: str,
+    ) -> int:
+        """
+        Uploads a file to a GitLab generic package.
+
+        Parameters
+        ----------
+        project : str
+            The project ID or the path of the project, including namespace.
+            Examples: `123` or `namespace/project`.
+        package_name : str
+            The name of the generic package.
+        package_version : str
+            The version of the generic package
+        file : str
+            The relative path of the file that is uploaded.
+        source : str
+            The source folder that is used as root when uploading.
+
+        Return
+        ------
+        int
+            Zero if everything went fine, non-zero coke otherwise.
+        """
+        ret = 1
+        fpath = os.path.join(source, pfile)
+        logger.debug("Uploading file %s from %s", pfile, source)
+        with open(fpath, "rb") as data:
             url = (
                 self.project_api_url(project)
                 + "packages/generic/"
@@ -151,13 +446,12 @@ class Packages:
                 + "/"
                 + parse.quote_plus(package_version)
                 + "/"
-                + parse.quote(str(file))
+                + parse.quote(pfile)
             )
-            res = request.urlopen(
-                request.Request(
-                    url, method="PUT", data=data, headers=self.get_headers()
-                )
+            req = request.Request(
+                url, method="PUT", data=data, headers=self.get_headers()
             )
-            if res.status == 201:  # 201 is created
-                ret = 0
+            with request.urlopen(req) as res:
+                if res.status == 201:  # 201 is created
+                    ret = 0
         return ret

{glpkg-1.1.0.dist-info → glpkg-1.3.0.dist-info}/METADATA

@@ -1,25 +1,19 @@
 Metadata-Version: 2.4
 Name: glpkg
-Version: 1.1.0
+Version: 1.3.0
 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
+Requires-Python: >=3.9
 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 - GitLab Generic Package tools 
 
-glpkg is a tool that makes it easy to work with [GitLab generic package registry](https://docs.gitlab.com/user/packages/generic_packages/).
+glpkg is a tool that makes it easy to work with [GitLab generic packages](https://docs.gitlab.com/user/packages/generic_packages/).
 
 
 ## Installation
@@ -47,7 +41,11 @@ By default, the used GitLab host is gitlab.com. If you use a self-hosted GitLab,
 
 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.
+Alternatively you can use a token stored in your `.netrc` file by setting `--netrc` argument.
+
+> If you use the tool in GitLab CI, read [below](#Use-in-GitLab-pipelines) on how to use the `CI_JOB_TOKEN`.
+
+The arguments related to the GitLab host or authentication (`--token`, `--netrc`, and `--ci`) are omitted in the examples below to focus on the commands.
 
 In general, run `glpkg --help` when needed.
 
@@ -74,7 +72,7 @@ mypackagename   2.0
 
 ### Download generic package
 
-To download everything from a specific generic package, run
+To download all files from a specific version of a generic package, run
 
 ```bash
 glpkg download --project 12345 --name mypackagename --version 1.0
@@ -85,7 +83,13 @@ Where:
 - `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.
+By default the files will be downloaded in the current working directory. To download the files to another directory, add argument `--destination` to the command. In all cases, as long as you have permissions to the destination directory, any pre-existing files will be overridden without warning.
+
+To download only a specific file from the package, add `--file` argument.
+
+```bash
+glpkg download --project 12345 --name mypackagename --version 1.5 --file the_only_one --destination /temp
+```
 
 > 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.
 
@@ -101,13 +105,21 @@ 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.
+- `my-file.txt` is the file that is uploaded to the generic package. Only relative paths are supported, and the relative path (e.g. `folder/file.txt`) is preserved when uploading the file to the package.
 
 > 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.
 
+To upload multiple files, or to upload a single file from a different directory, use `--source` argument. If no `--file` argument is set, all of the files in the source directory are uploaded, recursively. As an example, to upload all files from a `upload` folder to the package:
+
+```bash
+glpkg upload --project 12345 --name mypackagename --version 1.0 --source upload
+```
+
+Note: a file in `upload` folder will be uploaded to the root of the package. If you want to upload the file to a `dir` folder in the package, make a structure in the upload folder, like `upload/dir/`.
+
 ### 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.
+If you use the tool in a GitLab pipeline, setting argument `--ci` 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 or 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:
 
@@ -122,5 +134,4 @@ To use the `CI_JOB_TOKEN` with package registry of another projects, add `--proj
 
 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.

glpkg-1.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+gitlab/__init__.py,sha256=ZXRwtUQEDE9bdewmwKYCjMAhm5KsuvAe525_QBiWLHY,105
+gitlab/__main__.py,sha256=UPVixjP98KzJi9Ljth4yqqDTTaE3EfyAuj2xGCQAGys,586
+gitlab/cli_handler.py,sha256=2P3R-yYkT6D5CjNCAEd9FC9HYI09aJ_eyMSMsOHtZzs,12289
+gitlab/packages.py,sha256=50CbLdYxj0r6l8J40TxpIo2hTkKlv1BCFywFR6lg2nc,14785
+glpkg-1.3.0.dist-info/licenses/LICENSE.md,sha256=josGXvZq628dNS0Iru58-DPE7dRpDXzjJxKKT35103g,1065
+glpkg-1.3.0.dist-info/METADATA,sha256=4bQDKmHrf2da0eQ2hjfQKKItoirfcIr1VbWa3hwxbwY,6362
+glpkg-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+glpkg-1.3.0.dist-info/entry_points.txt,sha256=xHPZwx2oShYDZ3AyH7WSIvuhFMssy7QLlQk-JAbje_w,46
+glpkg-1.3.0.dist-info/top_level.txt,sha256=MvIaP8p_Oaf4gO_hXmHkX-5y2deHLp1pe6tJR3ukQ6o,7
+glpkg-1.3.0.dist-info/RECORD,,

glpkg-1.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-gitlab/__init__.py,sha256=EsSFZxYgGAL2i0sL5zkoz71JP7XbsWdg_jv_uOqrrXE,60
-gitlab/__main__.py,sha256=88VNY5Qrmn8g0rNcnjKNdN746--0chHsKBMH3PD3Nao,177
-gitlab/cli_handler.py,sha256=6B22RXAtOzVL-mpm7U3OPX1_SSrepQk12cwTG0TI3eU,6102
-gitlab/packages.py,sha256=l9tFEUsHMWF0vtv5ouVB4nvmWrJ4KDaS6f5e1lpjNyk,5683
-glpkg-1.1.0.dist-info/licenses/LICENSE.md,sha256=josGXvZq628dNS0Iru58-DPE7dRpDXzjJxKKT35103g,1065
-glpkg-1.1.0.dist-info/METADATA,sha256=65URv9IMuUo1XnmqKolpuJ12nkjcFKJg8rKMz4XeUIQ,5500
-glpkg-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-glpkg-1.1.0.dist-info/entry_points.txt,sha256=xHPZwx2oShYDZ3AyH7WSIvuhFMssy7QLlQk-JAbje_w,46
-glpkg-1.1.0.dist-info/top_level.txt,sha256=MvIaP8p_Oaf4gO_hXmHkX-5y2deHLp1pe6tJR3ukQ6o,7
-glpkg-1.1.0.dist-info/RECORD,,