Metadata-Version: 2.1
Name: xopera-template-library
Version: 0.2.3
Summary: Python CLI for managing template library.
Home-page: https://gitlab.xlab.si/radon/template-library-cli/-/tree/pypi
Author: XLAB d.o.o.
Author-email: pypi@xlab.si
License: UNKNOWN
Project-URL: Source Code, https://gitlab.xlab.si/radon/template-library-cli/-/tree/pypi
Project-URL: Bug Tracker, https://gitlab.xlab.si/radon/template-library-cli/-/issues
Description: # Template Library CLI
        This is a CLI client for the Template library.
        
        ## Table of Contents
          - [Introduction](#introduction)
            - [Prerequisites](#installation)
            - [Installation](#installation)
          - [Usage](#usage)
            - [Setup](#setup)
            - [Auth](#auth)
            - [Templates](#templates)
            - [Template groups](#template-groups)
            - [Users](#users)
            - [User groups](#user-groups)
        
        ## Introduction
        Template library CLI is called [`xopera-template-library`](https://pypi.org/project/xopera-template-library/) and is 
        available on [PyPI](https://pypi.org/project/xopera-template-library/) and 
        [TestPyPI](https://test.pypi.org/project/xopera-template-library/) instances. The tool can be used to view, upload and 
        download TOSCA template modules and their implementations. 
        
        ### Prerequisites
        `xopera-template-library` requires python 3 (and a virtual environment). In a typical modern Linux environment, we 
        should already be set. In Ubuntu, however, we might need to run the following commands:
        
        ```console
        $ sudo apt update
        $ sudo apt install -y python3-venv python3-wheel python-wheel-common
        ```
        
        ### Installation
        After the prerequisites are satisfy you can proceed with the installation.
        The simplest way to test `xopera-template-library` is to install it into virtual environment:
        
        ```console
        $ mkdir ~/opera && cd ~/opera
        $ python3 -m venv .venv && . .venv/bin/activate
        (.venv) $ pip install xopera-template-library
        ```
        
        ## Usage
        This part explains the usage of Template library CLI tool.
        
        ```console
        $ xopera-template-library template -h
        usage: xopera-template-library [-h] [-v]
                                       {template,template-group,user-group,user,setup,login,logout}
                                       ...
        
        positional arguments:
          {template,template-group,user-group,user,setup,login,logout}
            template            Template actions.
            template-group      Actions for groups of templates.
            user-group          Actions for groups of users.
            user                User info.
            setup               Setup client variables.
            login               Login to your account.
            logout              Logout of your account.
        
        optional arguments:
          -h, --help            show this help message and exit
          -v, --verbose         Increase output verbosity
        ```
        
        At any point the `-h/--help` (help) flag is available to display proceeding options. There is also `-v/--verbose` flag
        that will turn on the debug mode to see more output.
        
        ### Setup
        Before you begin using `xopera-template-library` tool you have to make sure that Template library REST API endpoint and
        KeyCloak auth endpoint are properly configured. This can be done with `setup` command where you will be able to change
        the default values that are:
        
        ```python
        # default REST API endpoint
        REST_API_ENDPOINT = "https://template-library-radon.xlab.si/api"
        # default KeyCloak endpoint
        KEYCLOAK_ENDPOINT = "https://openid-radon.xlab.si"
        ```
        
        If you run only `xopera-template-library setup` you will be able to modify only the REST API endpoint. You have to use
        `--keycloak` flag to tell the CLI that you will modify KeyCloak auth endpoint too.
        
        Examples:
        
        ```console
        $ xopera-template-library setup --keycloak
        Current Template Library REST API endpoint: https://template-library-radon.xlab.si/api
        Modify API endpoint (press enter to keep the current): 
        Template library REST API endpoint has been set to: https://template-library-radon.xlab.si/api.
        
        Current KeyCloak auth endpoint: https://openid-radon.xlab.si
        Modify KeyCloak endpoint (press enter to keep the current): 
        KeyCloak endpoint has been set to: https://openid-radon.xlab.si.
        ```
        
        ### Auth
        You can access public templates without authorizing.
        For other actions and to see your private templates, you need to login with your Keycloak identity provider account.
        
        You can login as:
        - XLAB KeyCloak user
        - Other identity provider's KeyCloak user (use `--identity-provider` flag)
        
        If `--identity-provider` and the ID are present, user will be logged in with the chosen identity provider.
        If you do not know the ID of the provider you can leave out the ID and the available providers will be listed and you
        will be able to choose one for authentication.
        
        Examples:
        
        ```console
        # login as XLAB KeyCloak user
        $ xopera-template-library login --username "username1" --password "password1"
        
        # login as another identity provider's KeyCloak user (you know identity provider ID)
        $ xopera-template-library login --username "username1" --password "password1" --identity-provider "identity_provider_ID"
        
        # login as another identity provider's KeyCloak user (you don't know identity provider ID)
        $ xopera-template-library login --username "username1" --password "password1" --identity-provider
        ```
        
        To logout, use `xopera-template-library logout`
        
        ### Templates
        Next you can use option `list` to display available templates.
        The templates will list in a table with templates' information.
        You can use filters for **keyword** (template name and description), template **type** and template **privacy** setting.
        Option `version` displays a list of template's published versions.
        
        Examples:
        
        ```console
        $ xopera-template-library template list
        $ xopera-template-library template list --keyword aws
        $ xopera-template-library template list --type node --public true
        $ xopera-template-library template version --name AwsLambda
        ```
        
        To download a template you have to provide a `path` to where you want the template to be saved and the name of the
        template to download. By default, the last version is downloaded.
        With argument `--version` you can download other versions.
        
        Example:
        
        ```console
        $ xopera-template-library template get --name DemoBlueprintOpenFaaS --path example/
        $ xopera-template-library template get --name DemoBlueprintOpenFaaS --path example/ --version 0.0.1
        ```
        
        If the desired template does not exist you can create and upload your own.
        You can start by generating a basic file structure by using `create` option.
        You will be asked for your template's name and type.
        
        Possible types are `data`, `artifact`, `capability`, `requirement`, `relationship`, `interface`, `node`, `group`,
        `policy`, `csar` and `other`.
        
        Examples:
        
        ```console
        $ xopera-template-library template create
        Template type: node
        Template name: ExampleTemplate
        ```
        
        When using the `xopera-template-library template create` CLI command this will automatically create the structure for
        your template, which contains the following files:
        
         ```console
        |-- Folder
                |-- files
                    |-- create.yml
                    |-- delete.yml
                |-- NodeType.tosca
                |-- README.md
        ```
        
        The structure is similar to [RADON particles](https://github.com/radon-h2020/radon-particles) and is compatible with 
        [Eclipse Winery](https://projects.eclipse.org/projects/soa.winery) modelling tool.
        
        After the basic files are generated you can edit them and upload your template to the library (use `save` CLI command).
        By default templates are private. For publishing your template publicly, add `--public` flag.
        
        Examples:
        
        ```console
        $ xopera-template-library template save --name AwsLambda --path example/AwsLambdaFunction --public --version 0.0.1
        ```
        
        ### Template groups
        Templates can be ordered in **template groups**. User can create a template group, list existing groups and get a list 
        of templates in a template group. Template group owners can add and remove templates.
        
        Examples:
        
        ```console
        $ xopera-template-library template-group create --group_name AwsGroup --group_description "A group of AWS related templates"
        $ xopera-template-library template-group list
        $ xopera-template-library template-group get --group_name AwsGroup
        $ xopera-template-library template-group add-template --group_name AwsGroup --template_name AwsBucket
        $ xopera-template-library template-group remove-template --group_name AwsGroup --template_name AwsBucket
        ```
        
        ### Users
        Users can look up their info, list user groups they are members of and list template groups they have access to.
        
        Examples:
        
        ```console
        $ xopera-template-library user info
        $ xopera-template-library user user-groups
        $ xopera-template-library user template-groups
        ```
        
        ### User groups
        Users can be members of **user groups**. User groups can be granted access to groups of templates. User can create a
        user group, list existing groups, get a list of users in a given user group and get a list of template groups a user
        group is granted access to.
        
        User group owners can add and remove users and access to template groups.
        
        Examples:
        
        ```console
        $ xopera-template-library user-group create --group_name RadonGroup --group_description "Members of Radon project"
        $ xopera-template-library user-group list
        $ xopera-template-library user-group get-users --group_name RadonGroup
        $ xopera-template-library user-group template-groups --group_name RadonGroup
        $ xopera-template-library user-group add-user --group_name RadonGroup --username johny
        $ xopera-template-library user-group remove-user --group_name RadonGroup --username johny
        $ xopera-template-library user-group add-templates --user_group RadonGroup --template_group AwsGroup
        $ xopera-template-library user-group remove-templates --user_group RadonGroup --template_group AwsGroup
        ```
        
Keywords: radon,templates,library,artifact,particles
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
