From adb5f3f179474c17a7575d492764ecea43b5a296 Mon Sep 17 00:00:00 2001 From: Grashalmbeisser <57599830+Grashalmbeisser@users.noreply.github.com> Date: Fri, 23 Feb 2024 15:15:23 +0100 Subject: [PATCH] Renewed Docstrings and Helptexts (#110) * documentation * Update README.md Co-authored-by: Jan Max Meyer * Update README.md Co-authored-by: Jan Max Meyer * Update README.md Co-authored-by: Jan Max Meyer * Update README.md Co-authored-by: Jan Max Meyer * Update README.md Co-authored-by: Jan Max Meyer * Update README.md Co-authored-by: Jan Max Meyer * Update README.md Co-authored-by: Jan Max Meyer --------- Co-authored-by: Jan Max Meyer --- README.md | 89 +++++++++++------- src/viur_cli/__init__.py | 2 - src/viur_cli/build.py | 53 ++++------- src/viur_cli/cli.py | 29 ++---- src/viur_cli/cloud.py | 193 ++++++++++++++++++++++++++++----------- src/viur_cli/conf.py | 12 ++- src/viur_cli/local.py | 46 +--------- src/viur_cli/package.py | 107 +++++++--------------- src/viur_cli/setup.py | 22 ++--- src/viur_cli/tool.py | 17 +--- src/viur_cli/update.py | 15 +-- 11 files changed, 277 insertions(+), 308 deletions(-) diff --git a/README.md b/README.md index a1b9202..ff8b217 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ ## What does it do? -`viur-cli` allows to control, maintain and develop a ViUR project from one central location by using the `viur` command. +`viur-cli` allows to control, maintain, develop and deploy a ViUR project from one central +location by using the `viur` command. ## Installation @@ -26,10 +27,16 @@ $ pipenv install --dev viur-cli ## Usage ```sh -$ viur --help +$ viur -h ``` will show all the commands that are currently supported by viur-cli +```sh +$ viur --version +``` +will show your current viur-cli version + + ```sh $ viur create myapp ``` @@ -37,28 +44,16 @@ this will create a new project folder, clone the base project and then call `viu you can use this to get started quickly with a new viur project from scratch. ```sh -$ viur init +$ viur run [profile] ``` -this will initialize a new project in the current folder, you will be asked a couple of questions like if -you would like to create a new project.json file, what components should be preinstalled and what the -projectID of your application will be. +run the appserver and start your app locally. You may specify a target profile. -```sh -$ viur run [target] -``` -run the appserver and start your app locally. You may specify a target projectID. ```sh -$ viur check {npm|--dev|--autofix} +$ viur check [--dev] ``` Runs a security check for the python environment and for each npm project registered under builds. -```sh -$ viur enable {backup} -``` -create a backup bucket and enable the gcloud service worker account to access it. - - ```sh $ viur package {install|update} {vi|scriptor|admin|all} ``` @@ -73,14 +68,13 @@ Arguments: - `version` version to install ```sh -$ viur build release -``` -build all npm apps and produce a release that can be deployed - -```sh -$ viur build app [appname] +$ viur build {app|clean|release} [option] ``` -build a specific app +Builds ViUR Project or specific apps +Commands: +- `app` Build a specific application +- `clean` Clean up Build Artifacts +- `release` Build all relevant applications to deploy the project ```sh $ viur cloud deploy {app|index|cloudfunction} {profile} {--ext|--yes|--name} @@ -88,10 +82,10 @@ $ viur cloud deploy {app|index|cloudfunction} {profile} {--ext|--yes|--name} This Function deploys the Google Cloud application and / or different .yaml files Scripts: - `app` Deploy application to the Google Appengine -- `index` Deploy index.yaml to Google Appenginge -- `cloudfunction` Deploy Cloudfunction to Google Appengine -Commands: -- `profile` The project.json profile you want to Work from + - `index` Deploy index.yaml to Google Appenginge + - `cloudfunction` Deploy Cloudfunction to Google Appengine + Commands: + - `profile` The project.json profile you want to Work from ```sh @@ -104,7 +98,7 @@ $ viur cloud setup {gcloud|gcroles} ``` Scripts: - `gcloud` This Function setups your project to work on the gcloud plattform -- `gcroles` This function lets you set up Roles for your google appengine Workspace + - `gcroles` This function lets you set up Roles for your google appengine Workspace ```sh @@ -113,17 +107,30 @@ $ viur cloud get {gcroles} Scripts: - `gcroles` This function lets you get Roles for your google appengine Workspace in a readable .json Format +```sh +$ viur package {update|install} {vi|admin|scriptor|all} [profile] [version] +``` +Performs operations on packages + +Scripts: +- `update` Updates an installed package +- `install` Installs a declared package + +Options: +- `vi` +- `admin` +- `scriptor` +- `all` ```sh $ viur env ``` -check the environment you are in right now, show versions of viur-cli, viur-core and vi etc. +Show information about your current environment. ```sh -$ viur project {add|remove|list} +$ viur project list ``` -with this you can manage your project.json or generate a new one. You can add or remove targets to/from the -project.json, list what has been added to the project.json, to be built when running `viur build release`. +Pretty prints your `project.json` file on the console. ```sh $ viur update {requirements} @@ -162,6 +169,20 @@ It contains the default viur project profile and it can be expanded with several "source": "" } }, + "gcloud": { + "functions": { //Declarations for a cloud function + "testfunction1": { + "entry-point": "main", + "env-vars-file": "env.yaml", + "memory": "512MB", + "runtime": "python311", + "source": "deploy/cloudfunction/function1", + "trigger": "http" + } + }, + "max-instances": "1", + "region": "europe-west3" + }, "core": "3.5.1", // viur-core version of your project "distribution_folder": "./deploy", // Deploy folder uploaded to GAE "sources_folder": "./sources", @@ -184,6 +205,7 @@ The GUI version is called scriptor and can be accessed via a webinterface, but v ```sh $ viur script {configure|pull|push|run|setup} ``` +Manage your ViUR Scriptor Scripts via the CLI Commands: - `configure` Manage configuration settings. - `pull` Pull contents from server to working_dir. @@ -240,7 +262,6 @@ viur-cli depends on * [app_server](https://github.com/XeoN-GHMB/app_server) * [pipfile-requirements](https://github.com/frostming/pipfile-requirements) * [watchgod](https://github.com/samuelcolvin/watchgod) -* [python-minifier](https://github.com/dflook/python-minifier) ## License diff --git a/src/viur_cli/__init__.py b/src/viur_cli/__init__.py index 91438f6..2b27745 100644 --- a/src/viur_cli/__init__.py +++ b/src/viur_cli/__init__.py @@ -1,7 +1,5 @@ from .cli import * from .conf import * -from .install import * -from .deploy import * from .package import * from .local import * from .build import * diff --git a/src/viur_cli/build.py b/src/viur_cli/build.py index d39c9f2..8f57026 100644 --- a/src/viur_cli/build.py +++ b/src/viur_cli/build.py @@ -9,7 +9,8 @@ def _build(conf, name, build_cfg, additional_args): - """Internal function to perform steps required for a given build configuration. + """ + Internal function to perform steps required for a given build configuration. This internal function is responsible for building an application according to the specified build configuration. It can handle two types of builds: @@ -39,6 +40,7 @@ def _build(conf, name, build_cfg, additional_args): :return: None """ + utils.echo_info(f"""- {build_cfg["kind"]} {name}""") match build_cfg["kind"]: case "npm": @@ -60,7 +62,8 @@ def _build(conf, name, build_cfg, additional_args): def _clean(conf, name, build_cfg): - """Perform steps required to clean a given build configuration. + """ + Perform steps required to clean a given build configuration. This internal function is responsible for cleaning the artifacts and files generated during the build process for a specified application. It supports two types of cleaning methods: @@ -137,23 +140,16 @@ def release(profile, additional_args): This command is used to build all relevant applications necessary for deploying the project. It allows you to specify the project configuration to use and any additional arguments to pass to the build process. - :param name: str, default: 'develop' - The name of the project configuration to use for building. This configuration can be either 'default' or a - project-specific configuration. - - :param additional_args: tuple - Additional arguments that can be passed to the build process. These arguments are passed to the underlying - build functions. - The `release` command loads the specified project configuration, which includes build configurations for individual applications. It then iterates through the applications and executes the build process for each one using the `_build` function. Note: - - Ensure that the specified project configuration exists. - - Additional arguments can be used to customize the build process. - :return: None + - Ensure that the specified project configuration exists. + + - Additional arguments can be used to customize the build process. + """ conf = config.get_profile(profile) utils.echo_info("building started...") @@ -175,21 +171,14 @@ def app(appname, profile, additional_args): This function is used to build a specific application as defined in your project's configuration. It allows you to specify the name of the application to build and any additional arguments to pass to the build process. - :param appname: str - The name of the application to build. It should correspond to an application defined in your project's - configuration. - - :param additional_args: tuple - Additional arguments that can be passed to the build process for the specified application. - The `app` function loads the default project configuration, selects the specified application's build configuration, and then executes the build process using the `_build` function. Note: - - Ensure that the specified application name is valid and defined in your project's configuration. - - Additional arguments can be used to customize the build process for this specific application. - :return: None + - Ensure that the specified application name is valid and defined in your project's configuration. + + - Additional arguments can be used to customize the build process for this specific application. """ conf = config.get_profile(profile) @@ -212,22 +201,20 @@ def clean(target, profile): This command is used to clean up build artifacts and files generated during the build process for one or more specific applications. It allows you to specify a target application or clean all applications in the project. - :param target: str, default: "" - The name of the target application to clean. If not provided, it will clean all applications defined in your - project's configuration. + The `clean` command performs the following actions: + - If a specific 'target' is provided, it cleans the build artifacts for that application. - The `clean` command performs the following actions: - - If a specific 'target' is provided, it cleans the build artifacts for that application. - - If 'target' is not provided, it cleans the build artifacts for all applications defined in your project's - configuration. + - If 'target' is not provided, it cleans the build artifacts for all applications defined in your project's + configuration. Note: - - When specifying a 'target,' ensure that it corresponds to a valid application defined in your project. - - Running the command without a 'target' will clean all applications. - :return: None + - When specifying a 'target,' ensure that it corresponds to a valid application defined in your project. + + - Running the command without a 'target' will clean all applications. """ + conf = config.get_profile(profile) builds = conf.get("builds", {}) diff --git a/src/viur_cli/cli.py b/src/viur_cli/cli.py index c340f37..24b3ffe 100644 --- a/src/viur_cli/cli.py +++ b/src/viur_cli/cli.py @@ -7,6 +7,7 @@ import semver import pprint + @click.group(invoke_without_command=True, no_args_is_help=True, context_settings={"help_option_names": ["-h", "--help"]}) @@ -16,26 +17,14 @@ def cli(ctx): """ Command-line interface for managing project configuration and information. - The viur-cli provides a set of commands to manage your project's configuration in the 'project.json' - if missing. It also offers commands to view and modify project information. - - Usage: - ``` - viur [OPTIONS] COMMAND [ARGS]... - ``` - - Options: - -h, --help Show this message and exit. - --version Show the CLI tool's version. - - Commands: - project Manage project.json and generate if missing. + The viur-cli provides a set of commands to manage your project's configuration in the 'project.json'. + It also offers commands to view and modify project information. Note: - - Use the `--version` option to display the CLI tool's version. - - Run the 'project' command to manage 'project.json' and project configuration settings. - :return: None + - Use the `--version` option to display the CLI tool's version. + + - Run the 'project' command to manage 'project.json' and project configuration settings. """ # Get the systems pipenv Version Number @@ -48,14 +37,11 @@ def cli(ctx): if semver.compare(sys_pipenv, MINIMAL_PIPENV) < 0: echo_warning( f"Your pipenv Version does not match the recommended pipenv version. \n" - f"This mismatch may cause Errors, please consider to update your Systems pipenv version \n" + f"This mismatch may cause Errors, please consider updating your Systems pipenv version \n" f"Your Version: {sys_pipenv}\n" f"Recommended Version: {MINIMAL_PIPENV}" ) - - - @cli.command() @click.argument("action", type=click.Choice(['list'])) @click.argument("profile", default="default") @@ -65,4 +51,3 @@ def project(action, profile): if action == "list": echo_info(f"These are the Settings for {profile} profile") pprint.pprint(project_config) - diff --git a/src/viur_cli/cloud.py b/src/viur_cli/cloud.py index 3b71255..6f19c71 100644 --- a/src/viur_cli/cloud.py +++ b/src/viur_cli/cloud.py @@ -12,20 +12,38 @@ @cli.group() def cloud(): - """Manage cloud Actions""" + """This method defines a command group for working with cloud resources.""" @cloud.command(context_settings={"ignore_unknown_options": True}) @click.argument("action", type=click.Choice(["backup"])) def enable(action): - """ - Enable specific features for the project. - """ + """Enable a specific action based on the provided parameter.""" if action == "backup": enable_gcp_backup() def enable_gcp_backup(): + """ + Enables Google Cloud Platform backups for the project. + + This method performs the following steps: + 1. Loads the project configuration using the "default" profile. + 2. Creates helper variables for the project ID and the backup bucket name. + 3. Constructs the command to create the backup bucket using gsutil. + 4. Executes the command to create the backup bucket. + 5. If the bucket creation fails, it prints an error message. + 6. Creates helper variables for the IAM roles and the service worker email. + 7. Adds the IAM policy bindings for the service worker with the specified roles. + 8. If an error occurs during the role binding, it prints an error message. + 9. Prints a success message. + + Note: + - The backup bucket is created in the europe-west3 region. + - The IAM roles "roles/storage.admin" and "roles/datastore.importExportAdmin" are used. + + :return: None + """ # Load the project Config conf = config.get_profile("default") @@ -69,14 +87,35 @@ def enable_gcp_backup(): @cloud.command(context_settings={"ignore_unknown_options": True}) @click.argument("action", type=click.Choice(["backup"])) def disable(action): - """ - Disable specific features for the project. - """ + """Disables a specific action.""" if action == "backup": disable_gcp_backup() def disable_gcp_backup(): + """ + Disables Google Cloud Platform(GCP) backups for a specified project. + + This method disables GCP backups by performing the following steps: + 1. Loads the project configuration from the "default" profile. + 2. Creates helper variables for the project ID and backup bucket name. + 3. Removes the backup bucket by executing the appropriate command using gsutil. + 4. If an error occurs during bucket removal, an error message is printed. + 5. Creates helper variables for the IAM roles and service worker email. + 6. Removes the IAM policy bindings for the specified roles using the gcloud command. + 7. If an error occurs during roles removal, an error message is printed. + 8. Prints a success message if all steps complete successfully. + + Returns: + None + + Raises: + Any exception that occurs during the execution of the method. + + Note: + - Make sure to have the correct Google Cloud Access rights. + """ + # Load the project Config conf = config.get_profile("default") @@ -115,14 +154,16 @@ def disable_gcp_backup(): ) return - print('Success! Gcloud Backups have been disabled') + echo_info('Success! Gcloud Backups have been disabled') @cloud.command(context_settings={"ignore_unknown_options": True}) @click.argument("action", type=click.Choice(["gcloud", "gcroles"])) @click.argument("profile", default="default") def setup(action, profile): - """Setup project for different Cloud Services""" + """ + Set up the specified action for the given profile. + """ if action == "gcloud": gcloud_setup() @@ -134,13 +175,27 @@ def setup(action, profile): @click.argument("action", type=click.Choice(["gcroles"])) @click.argument("profile", default='default') def get(action, profile): - """Setup project for different Cloud Services""" + """Get Method to retrieve Information from Cloud Service Environment""" if action == "gcroles": gcloud_get_roles(profile) def gcloud_get_roles(profile): + """ + Retrieve IAM roles from Google Cloud Platform using the gcloud command-line tool. + + :param profile: String: + The profile name to use for retrieving the roles. + + :raises: + subprocess.CalledProcessError: If an error occurs while fetching the role data. + + Note: + - This method requires the gcloud command-line tool to be installed and configured in the environment. + - The gcloud configuration file should contain the necessary authentication information. + + """ conf = config.get_profile(profile) try: @@ -174,6 +229,16 @@ def gcloud_get_roles(profile): def gcloud_setup_roles(profile): + """ + Sets up roles in Google Cloud Platform (GCP) based on the given profile. + + :param profile: The profile to use for setting up roles in GCP + :type profile: str + + :raises json.JSONDecodeError: If there is an error decoding JSON from the roles JSON file + :raises yaml.YAMLError: If there is an error opening or writing the .yaml file + + """ conf = config.get_profile(profile) # Use a more descriptive variable name for the JSON file @@ -203,6 +268,9 @@ def gcloud_setup_roles(profile): def transform_yaml_to_dict(dict_data): + """ + Transforms a YAML file to a dict Object + """ transformed_data = {'bindings': []} # Create a dictionary to store unique members and their corresponding roles @@ -224,6 +292,15 @@ def transform_yaml_to_dict(dict_data): def transform_dict_to_yaml(transformed_data): + """ + Transforms a dictionary to YAML format. + + :param transformed_data: Dictionary + The transformed data in dictionary format. + + :returns: dict + The original data in YAML format. + """ original_data = {'bindings': []} # Create a dictionary to store roles and their corresponding members @@ -252,6 +329,24 @@ def transform_dict_to_yaml(transformed_data): def gcloud_setup(): + """ + Set up the Google Cloud Platform (GCP) environment for a ViUR project. + + This method performs the following steps: + 1. Prompts the user to enter the GCP project ID. + 2. Checks if the user is authorized with gcloud. + - If not authorized, prompts the user to authenticate with gcloud and login. + 3. Checks if the GCP App Engine app already exists. + - If not, prompts the user to create the app and confirm the project is connected to a billing account. + 4. Enables necessary APIs and services for the project. + 5. Configures Google Cloud Storage for the project. + 6. Deploys necessary deployment files (cron.yaml, queue.yaml, index.yaml) to the project. + 7. Checks if the app engine default credentials are set. + - If not set, prompts the user to authenticate and set the application default user. + 8. Prints a success message with instructions on how to run the project locally. + + Note: This method does not return anything. + """ project = input("Enter PROJECT_ID: ").strip() if not project: @@ -292,7 +387,7 @@ def gcloud_setup(): ) response = input("Continue? [Y/n] ") if not response.lower() in ("y", ""): - print("User aborted.") + echo_error("User aborted.") return # Create the Appengine app @@ -350,6 +445,12 @@ def gcloud_setup(): # Helper function for running Commands in subprocess and getting the Output def run_command(command): + """ + Executes the specified command in the system shell and returns the output. + + :param command: String + The command to be executed in the Subprocess. + """ try: return subprocess.check_output(command, shell=True) except subprocess.CalledProcessError as e: @@ -364,48 +465,7 @@ def run_command(command): @click.option("--yes", "-y", is_flag=True, default=False) @click.option("--name", "-n", default=None) def deploy(action, profile, name, ext, yes, additional_args): - - """ - Deploy a Google Cloud application or different YAML files. - - This command allows you to deploy various components of a Google Cloud application, such as the app itself, - index.yaml configurations, cron.yaml configurations, or queue.yaml configurations. - The deployment action and the specific project configuration - to deploy are determined by the 'action' and 'name' parameters. - Please make sure to configure your global installation of the gcloud-cli accordingly. - - :param action: str - The deployment action. It can be one of the following: - - 'app': Deploy the Google Cloud application. - - 'index': Deploy the index.yaml configuration. - - 'cron': Deploy the cron.yaml configuration. - - 'queue': Deploy the queue.yaml configuration. - - :param name: str, default: 'develop' - The name of the project configuration to use for deployment. - It should correspond to a valid project configuration. - - :param additional_args: tuple - Additional arguments that can be passed to the deployment process. - - Example Usage: - ```shell - viur deploy app my_config --version v2 - viur deploy index my_config - viur deploy cron my_config - viur deploy queue my_config - ``` - - The `deploy` command deploys the specified components based on the 'action' and 'name' parameters. - It includes checks for successful deployments and offers a confirmation prompt for any failed checks. - - Note: - - Ensure that the specified project configuration ('name') is valid and defined in your project's configuration. - - The 'app' action includes vulnerability checks and a confirmation prompt if checks fail. - - The 'index' action sorts the index.yaml file by kind for cleaner organization. - - :return: None - """ + """ Deploy the specified action to a cloud service.""" conf = config.get_profile(profile) @@ -496,7 +556,29 @@ def deploy(action, profile, name, ext, yes, additional_args): def build_deploy_command(name, conf): - """Builds the deployment command string for the cloud function.""" + """ + + Builds a deployment command for a cloud function. + + :param name: The name of the cloud function to deploy. If not provided, the user will be prompted to enter it. + :type name: str + :param conf: The project configuration. + :type conf: dict + :return: The deployment command. + :rtype: str + + The method builds a command for deploying a cloud function using the Google Cloud Platform (GCP) CLI. It first checks if the name of the cloud function is provided. If not, it prompts + * the user to enter it using the `click.prompt` function. It then checks if the provided name exists in the project configuration. + + The deployment command is built using a formatted string that includes the function name and the specified region. Additionally, the `max-instances` parameter from the project configuration + * is included in the command. + + Next, the method iterates over the configuration of the specified cloud function and adds additional parameters to the command based on the key-value pairs. If the key is "trigger", + * "update", "set", or "remove", it adds a flag to the command including the key and its corresponding value. Otherwise, it adds a flag to the command including the key and its corresponding + * value as a string. + + Finally, the built command is returned. + """ if not name: name = click.prompt("Please enter the name of the cloudfunction you want to deploy") @@ -532,7 +614,7 @@ def build_deploy_command(name, conf): @click.option("--runtime", "-rt") @click.option("--trigger", "-tr") def create(profile, action, source, name, entrypoint, env_vars_file, memory, runtime, trigger): - """Create cloudfunction entry""" + """Creates a cloud function based on the provided parameters.""" if action == "function": conf = config.get_profile(profile) # First layer initialization: @@ -571,3 +653,4 @@ def create(profile, action, source, name, entrypoint, env_vars_file, memory, run config.migrate() echo_positive("Your cloudfunction creation was succesfull, if you want to add more flags, " "add them in your project.json under") + diff --git a/src/viur_cli/conf.py b/src/viur_cli/conf.py index cbfce73..422b49e 100644 --- a/src/viur_cli/conf.py +++ b/src/viur_cli/conf.py @@ -2,7 +2,6 @@ import click from .utils import * - PROJECT_CONFIG_FILE = "project.json" PROJECT_CONFIG_VERSION = "2.0.0" @@ -31,7 +30,6 @@ def load(self): The project configuration loaded from the project.json file. """ - # Search in any parent folder for a project.json, # change working directory because subsequent commands # require for project root folder. @@ -54,7 +52,8 @@ def load(self): echo_fatal(f"Can't open {PROJECT_CONFIG_FILE} for reading") except json.decoder.JSONDecodeError as e: - echo_fatal(f"The configuration in {PROJECT_CONFIG_FILE} contains invalid JSON: {str(e)}. Please verify right syntax.") + echo_fatal( + f"The configuration in {PROJECT_CONFIG_FILE} contains invalid JSON: {str(e)}. Please verify right syntax.") self.migrate() @@ -63,15 +62,17 @@ def save(self): Write the current projectConfig dictionary to project.json. """ with open(PROJECT_CONFIG_FILE, "w") as f: - json.dump(self, f, indent=4, sort_keys=True)) + json.dump(self, f, indent=4, sort_keys=True) f.write('\n') def get_profile(self, profile): + """Get profile configuration""" if profile == "format": echo_fatal("Your profile can not be named 'Format' ") return self["default"].copy() | self[profile] def delete(self): + """Delete profile cofniguration""" configname = click.prompt('name') try: del self[configname] @@ -124,7 +125,7 @@ def migrate(self): if entry in self["default"]: version_value = self["default"][entry].lstrip("v") self["default"]["builds"][entry] = { - "command": f"viur install {entry}", + "command": f"viur package install {entry}", "kind": "exec", "version": version_value } @@ -158,4 +159,5 @@ def migrate(self): # conf updates must increase format version self.save() + config = ProjectConfig() diff --git a/src/viur_cli/local.py b/src/viur_cli/local.py index 396c1da..a1dfe96 100644 --- a/src/viur_cli/local.py +++ b/src/viur_cli/local.py @@ -14,25 +14,7 @@ def run(profile, additional_args): """ Start your application locally. - - The 'run' command allows you to start your ViUR application locally. You can specify the configuration to use - and provide additional arguments to the 'app_server' command. - - :param name: str, default: 'develop' - The name of the configuration to use. The 'develop' configuration is the default. - - :param additional_args: List[str] - Additional arguments to pass to the 'app_server' command when running the application. - - Example Usage: - ```shell - viur run develop --port 8080 - viur run production - ``` - The 'run' command launches your ViUR application locally specified configuration and optional arguments. - - :return: None """ conf = config.get_profile(profile) @@ -45,18 +27,9 @@ def env(profile): """ Check the local environment for ViUR development. - The 'env' command checks the local environment for ViUR development and reports the status of various tools - and dependencies. It helps you ensure that your development environment is correctly set up. - - Usage: - ```shell - viur env - ``` - The 'env' command provides information about the versions tools and dependencies, such as ViUR-CLI, app_server, git, Python, npm, node, and more. It checks the availability of these tools and reports their versions. - :return: None """ valid_icon = "\U00002714" @@ -158,24 +131,9 @@ def env(profile): @cli.command() @click.option('--dev', '-d', is_flag=True, default=False) def check(dev): - """Perform security checks for vulnerabilities. - - The 'check' command performs security checks for vulnerabilities within your project. - It checks for vulnerabilities in the Pipenv and npm dependencies of your project. - You can choose to include development dependencies by using the - '--dev' option. - - :param dev: bool, default: False - Perform checks on development dependencies if set to 'True'. - - Example Usage: - ```shell - viur check --dev - ``` - + """ + Perform security checks for vulnerabilities. The 'check' command helps you identify and address security vulnerabilities in your project's dependencies. - - :return: None """ if do_checks(dev): diff --git a/src/viur_cli/package.py b/src/viur_cli/package.py index c412e4c..f435370 100644 --- a/src/viur_cli/package.py +++ b/src/viur_cli/package.py @@ -19,26 +19,38 @@ def get_version_info(software: str, version: str) -> tuple[str, str]: """ - get_version_info(software: str, version: str) -> tuple[str, str] + :param software: String + Name of the ViUR Software - Retrieves version information for a software from a given repository. + :param version: String + Desired version of the ViUR Software - Parameters: - - software: A string representing the name of the software. - - version: A string representing the version of the software. + :returns: tuple[str, str] + real version and download URL - Returns: - A tuple containing the real version (str) and the download URL (str) for the software. + Description: + This method takes in the name of a software and a desired version, + and returns the real version and download URL for that software. - Note: - - The version should be provided without a leading "v". - - If the version is set to "latest", the latest release information and download URL will be fetched. - - If the version is a valid existing release, the real version will be saved to the config. - - If the version is not a valid existing release, the real_version will be None (Unknown). - - The download URL will be constructed based on the real_version and the download name for the software. + The 'software' parameter is a string that represents the name of the software. - Example Usage: - real_version, download_url = get_version_info("sample_software", "1.2.3") + The 'version' parameter is a string that represents the desired version of the software. + If the version starts with 'v', it will be normalized by removing the leading 'v'. + *The 'version' can also be set as 'latest' to get the latest version available. + + The method uses the provided 'software' parameter to fetch the repository + and download information from REPOS dictionary. + + If the 'version' is 'latest', the method constructs the URL using the repository information to fetch the + latest release information from GitHub API. If the request fails, an error message + * will be displayed. If the request is successful, the real version of the latest release is obtained + and saved in the config. + + If the 'version' is not 'latest', the method constructs the URL using the repository and desired version information. + If the request for the version tag information fails, the method + * falls back to the previously obtained real version. Else, the tag is used to construct the download URL. + + Finally, the method returns a tuple containing the real version and download URL. """ repo, download_name = REPOS[software] @@ -77,21 +89,7 @@ def get_version_info(software: str, version: str) -> tuple[str, str]: @click.argument("version", default="latest") def package(operation, component, profile, version): """ - This method is used to handle packet operations, such as updating or installing components. - - Parameters: - - operation (str): The operation to perform. Must be either 'update' or 'install'. - - component (str): The component to update or install. Must be one of: 'vi', 'admin', 'scriptor', 'all'. - - profile (str, optional): The profile to use. Defaults to 'default'. - - version (str, optional): The version of the component to update or install. Defaults to 'latest'. - - Note: The 'all' component option is only applicable to the 'update' operation. - - Examples: - packet('update', 'vi') -> Updates 'vi' component to the latest version using the default profile. - packet('install', 'admin', profile='prod', version='1.0') -> Installs 'admin' component with version '1.0' using the 'prod' profile. - packet('update', 'all', version='2.0') -> Updates all components to version '2.0' using the default profile. - + Performs installements and updates of ViUR Ecosystem packages """ conf = config.get_profile(profile) operations_links = { @@ -126,14 +124,7 @@ def perform_operation(component, version): def checkreturncode(output): """ - Checks the return code of a command execution and prints a message based on the return code. - - Parameters: - - output: A subprocess.CompletedProcess object representing the output of a command execution. - - Returns: - None - + Check the return code of a process output. """ if output.returncode == 0: echo_positive("update was successful") @@ -143,15 +134,7 @@ def checkreturncode(output): def scriptor(version, target, profile): """ - Update the Scriptor tool to the specified version. - - Parameters: - - version (str): The version of Scriptor to update to. - - target (str): The target directory for the updated Scriptor tool. - - profile (str): The specific profile to use for configuration. - - Returns: - None + Update the Scriptor tool to a specified version. """ conf = config.get_profile(profile) dist_folder = conf["distribution_folder"] @@ -187,20 +170,7 @@ def step_label(step: int) -> str: def admin(version: str, target: str, profile): - """ - Updates the admin tool to a specified version. - - Parameters: - version (str): The version of the admin tool to update to. - target (str): The target folder to update the admin tool in. - profile: The profile to use for configuration. - - Returns: - None - - Example Usage: - admin("1.2.0", "C:/admin", "production") - """ + """Update the admin to a specific version.""" conf = config.get_profile(profile) dist_folder = conf["distribution_folder"] @@ -239,20 +209,7 @@ def step_label(step: int) -> str: def vi(version, target, profile): - """ - Updates the version of vi based on the provided parameters. - - Parameters: - - version (str): The version of vi to update to. - - target (str): The target folder where vi will be installed. - - profile (str): The profile to use for configuration. - - Returns: - None - - Example: - vi("1.2.3", "/path/to/vi", "production") - """ + """Updates Vi to the specified version.""" conf = config.get_profile(profile) dist_folder = conf["distribution_folder"] diff --git a/src/viur_cli/setup.py b/src/viur_cli/setup.py index e7cd3f9..86e0431 100644 --- a/src/viur_cli/setup.py +++ b/src/viur_cli/setup.py @@ -4,6 +4,7 @@ from .cli import cli from .utils import * + @cli.command() @click.argument("name") @click.pass_context @@ -14,25 +15,20 @@ def create(ctx, name): The 'create' command allows you to create a new ViUR project by cloning the ViUR base project and configuring it. You can specify the name of the new project as the 'name' argument. - :param name: str - The name of the new ViUR project. + The 'create' command performs the following steps: - Example Usage: - ```shell - viur create my_new_project - ``` + 1. Clones the ViUR base project from the official GitHub repository. - The 'create' command performs the following steps: - 1. Clones the ViUR base project from the official GitHub repository. - 2. Configures the new project by running 'clean-base.py'. - 3. Optionally configures the project as a new gcloud project (if confirmed). + 2. Configures the new project by running 'clean-base.py'. + + 3. Optionally configures the project as a new gcloud project (if confirmed). Note: - - This command initializes the new ViUR project based on the ViUR base project. - - Make sure to provide a unique project name to avoid conflicts with existing folders. + - This command initializes the new ViUR project based on the ViUR base project. + + - Make sure to provide a unique project name to avoid conflicts with existing folders. - :return: None """ if os.path.exists(f'./{name}'): echo_error(f'"{name}" Folder exists. Please use a different name or remove this folder ./{name}') diff --git a/src/viur_cli/tool.py b/src/viur_cli/tool.py index 56c8a8a..1c119bd 100644 --- a/src/viur_cli/tool.py +++ b/src/viur_cli/tool.py @@ -12,24 +12,13 @@ def tool(): The 'tool' group allows you to execute various ViUR-related scripts that help with tasks such as project porting, Pyodide installation, and SSL certificate fixes. - Usage: - ``` - viur tool [options] - ``` - Available Commands: - - '2to3': ViUR porting script. - - 'pyodide': Run the get_pyodide command. - - 'ssl_fix': SSL certificate fix for macOS. - Use 'viur tool -h' for command-specific help. + - '2to3': ViUR porting script. - Example Usage: - ``` - viur tool 2to3 /path/to/project - ``` + - 'pyodide': Run the get_pyodide command. - :return: None + - 'ssl_fix': SSL certificate fix for macOS. """ diff --git a/src/viur_cli/update.py b/src/viur_cli/update.py index 4df4568..3b9249f 100644 --- a/src/viur_cli/update.py +++ b/src/viur_cli/update.py @@ -16,22 +16,15 @@ def update(action, profile, additional_args): This command allows you to update project-specific files and dependencies for a specified project configuration. Currently, it supports the 'requirements' action, which is used to update the requirements. - - :param action: str - The action to perform. Currently, only 'requirements' is supported for updating requirements or dependencies. - :param name: str, default: 'develop' - The name of the project configuration to update. It should correspond to a valid project configuration. - :param additional_args: tuple - Additional arguments that can be passed to the update process. - The `update` command performs the specified 'action' to update project-specific files or dependencies. It ensures that the specified project configuration exists. Note: - - Ensure that the specified project configuration ('name') is valid and defined in your project's configuration. - - Additional arguments can be used to customize the update process if supported by the action. - :return: None + - Ensure that the specified project configuration ('name') is valid and defined in your project's configuration. + + - Additional arguments can be used to customize the update process if supported by the action. + """ conf = config.get_profile(profile)