mdps-app-generator


Namemdps-app-generator JSON
Version 1.0.0 PyPI version JSON
download
home_pageNone
SummaryGenerates an OGC compliant Unity application package using the Unity app-pack-generator.
upload_time2025-02-20 19:05:30
maintainerNone
docs_urlNone
authorJames McDuffie
requires_python>=3.9
licenseApache License
keywords unity-sds ogc packaging cwl jupyter
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <!-- Header block for project -->
<hr>

<div align="center">

![logo](https://user-images.githubusercontent.com/3129134/163255685-857aa780-880f-4c09-b08c-4b53bf4af54d.png)

<h1 align="center">Unity Application Generator</h1>
<!-- ☝️ Replace with your repo name ☝️ -->

</div>

<pre align="center">Creates and registers a Unity OGC application package</pre>

<!-- Header block for project -->

[app-pack-generator](https://github.com/unity-sds/app-pack-generator) | [unity-example-application](https://github.com/unity-sds/unity-example-application)

## Features

* Uses [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create CWL, application descriptor and Docker image
* Can output Jupyter noteboook parameterization for debugging purposes
* Pushes generated Docker image to a Docker registry
* Pushes generated application package files to a Dockstore application registry


## Requirements

* [app-pack-generator](https://github.com/unity-sds/app-pack-generator)
* [Unity-py](https://pypi.org/project/unity-sds-client/)

## Setup Instructions

### Install from Github

```
pip install git+https://github.com/unity-sds/unity-app-generator.git 
```

### Install Locally

```
git clone https://github.com/unity-sds/unity-app-generator.git
pip install unity-app-generator
```

## Usage

Unity application generation is accomplished by using the `build_ogc_app` program. It uses a stateful architecture such as in other programs such as ``git`` where actions on a repository can be done in a series of steps. These steps are listed when running `build_ogc_app --help`.

```
usage: build_ogc_app [-h] [--state_directory STATE_DIRECTORY] {init,build_docker,push_docker,parameters,build_cwl,push_app_registry} ...

Unity Application Package Generator

positional arguments:
  {init,build_docker,push_docker,parameters,build_cwl,push_app_registry}
    init                Initialize a Git repository for use by this application. Creates a .unity_app_gen directory in the destination directory
    build_docker        Build a Docker image from the initialized application directory
    push_docker         Push a Docker image from the initialized application directory to a remote registry
    parameters          Display parsed notebook parameters
    build_cwl           Create OGC compliant CWL files from the repository and Docker image
    push_app_registry   Push CWL files to Dockstore application registry

options:
  -h, --help            show this help message and exit
  --state_directory STATE_DIRECTORY
                        An alternative location to store the application state other than .unity_app_gen
```

By default a state directory name `.unity_app_gen` is created in the repository the tool is targeting. Usually this is within the repository directory itself unless the `--state_directory` argument is used. This directory contains metadata information and generated files created by steps and needed for subsequent steps.

### init

Before using the tool with a repository the state directory needs to be initialized:

```
usage: build_ogc_app init [-h] [-c CHECKOUT] source_repository [destination_directory]

positional arguments:
  source_repository     Directory or Git URL of application source files, default is current directory
  destination_directory
                        Directory where to check out source repository, default is a directory under the current subdirectory with same basename as the
                        source_repository

options:
  -h, --help            show this help message and exit
  -c CHECKOUT, --checkout CHECKOUT
                        Git hash, tag or branch to checkout from the source repository
```

This can be accomplished with an existing clone of a repository or the tool can clone the repository locally for you. If no directory is supplied the tool will assume you would like to initialize the current directory. When working interatively it is suggested to change to the directory you are working with and use the script from there. This simplifies program usage and does not require you to use the `--state_directory` argument on each call. 

For example to initialize an repository and use it locally:

```
git clone https://github.com/unity-sds/unity-example-application.git
cd unity-example-application
build_ogc_app init
```

Or to have the tool clone and initialize the repository for you:

```
build_ogc_app init https://github.com/unity-sds/unity-example-application.git unity-example-application
cd unity-example-application
```

### build_docker

The `build_docker` command does not require any additional arguments. It will utilize [app-pack-generator](https://github.com/unity-sds/app-pack-generator) and [repo2docker](https://github.com/jupyterhub/repo2docker), please see the documentation there for how to set up your repository for a successful build. The built Docker image name will be stored into `app_state.json` file in the state directory. This command requires the `init` step to have already been run.

### push_docker

This command will push a Docker image built by the `build_docker` step to a remote Docker registry. It will then record the remote registry URL into the state directory for use by subsequent steps. The `push_docker` command has a required argument of either the URL of a remote Docker registry or a Dockerhub username. It is assumed you have already used `docker login` to initialze credentials. This command requires the `build_docker` step to have already been run.

### build_cwl

The `build_cwl` will use [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create OGC compliant CWL files based on the parameterization of the Jupyter notebook in the target repository. Currently the Jupyter notebook is required to be named `process.ipynb`. Please see the [app-pack-generator](https://github.com/unity-sds/app-pack-generator) documentation for how to properly parameterize a notebook. The generated CWL files and application descriptor will be placed in the state directory. If the `push_docker ` step has not yet been run the CWL files will refer to the local Docker image tag instead a remote URL.

### push_app_registry

The `push_app_registry` command pushes the generated CWL into a Dockstore application registry server. It requires the the URL to the Dockstore API as well as a token obtained through the Dockstore interface. The `build_cwl` step is required to have already been executed.

```
usage: build_ogc_app push_app_registry [-h] --api_url DOCKSTORE_API_URL --token DOCKSTORE_TOKEN

options:
  -h, --help            show this help message and exit
  --api_url DOCKSTORE_API_URL
                        Dockstore API URL including the trailing api/ portion of the URL
  --token DOCKSTORE_TOKEN
                        Dockstore API token obtained from the My Services / Account page
```

The API URL can be obtained from the Dockstore user interface by scrolling to the bottom and clicking the API link in the footer. It will be the portion of the URL up to the `/api` path. The API token is obtained by logging into the Dockstore, clocking on the username drop down in the top right corner then selecting the Account item. Copy the token from the Dockstore Account item.

## Changelog

See our [CHANGELOG.md](CHANGELOG.md) for a history of our changes.

See our [releases page](https://github.com/unity-sds/unity-app-generator/releases) for our key versioned releases.

## License

See our: [LICENSE](LICENSE.txt)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mdps-app-generator",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "unity-sds, ogc, packaging, cwl, jupyter",
    "author": "James McDuffie",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/87/11/c3f3f8ba25d8e518eb117a7e1f98cca8b0cb29a6e062ce9b385c5672dfde/mdps_app_generator-1.0.0.tar.gz",
    "platform": null,
    "description": "<!-- Header block for project -->\n<hr>\n\n<div align=\"center\">\n\n![logo](https://user-images.githubusercontent.com/3129134/163255685-857aa780-880f-4c09-b08c-4b53bf4af54d.png)\n\n<h1 align=\"center\">Unity Application Generator</h1>\n<!-- \u261d\ufe0f Replace with your repo name \u261d\ufe0f -->\n\n</div>\n\n<pre align=\"center\">Creates and registers a Unity OGC application package</pre>\n\n<!-- Header block for project -->\n\n[app-pack-generator](https://github.com/unity-sds/app-pack-generator) | [unity-example-application](https://github.com/unity-sds/unity-example-application)\n\n## Features\n\n* Uses [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create CWL, application descriptor and Docker image\n* Can output Jupyter noteboook parameterization for debugging purposes\n* Pushes generated Docker image to a Docker registry\n* Pushes generated application package files to a Dockstore application registry\n\n\n## Requirements\n\n* [app-pack-generator](https://github.com/unity-sds/app-pack-generator)\n* [Unity-py](https://pypi.org/project/unity-sds-client/)\n\n## Setup Instructions\n\n### Install from Github\n\n```\npip install git+https://github.com/unity-sds/unity-app-generator.git \n```\n\n### Install Locally\n\n```\ngit clone https://github.com/unity-sds/unity-app-generator.git\npip install unity-app-generator\n```\n\n## Usage\n\nUnity application generation is accomplished by using the `build_ogc_app` program. It uses a stateful architecture such as in other programs such as ``git`` where actions on a repository can be done in a series of steps. These steps are listed when running `build_ogc_app --help`.\n\n```\nusage: build_ogc_app [-h] [--state_directory STATE_DIRECTORY] {init,build_docker,push_docker,parameters,build_cwl,push_app_registry} ...\n\nUnity Application Package Generator\n\npositional arguments:\n  {init,build_docker,push_docker,parameters,build_cwl,push_app_registry}\n    init                Initialize a Git repository for use by this application. Creates a .unity_app_gen directory in the destination directory\n    build_docker        Build a Docker image from the initialized application directory\n    push_docker         Push a Docker image from the initialized application directory to a remote registry\n    parameters          Display parsed notebook parameters\n    build_cwl           Create OGC compliant CWL files from the repository and Docker image\n    push_app_registry   Push CWL files to Dockstore application registry\n\noptions:\n  -h, --help            show this help message and exit\n  --state_directory STATE_DIRECTORY\n                        An alternative location to store the application state other than .unity_app_gen\n```\n\nBy default a state directory name `.unity_app_gen` is created in the repository the tool is targeting. Usually this is within the repository directory itself unless the `--state_directory` argument is used. This directory contains metadata information and generated files created by steps and needed for subsequent steps.\n\n### init\n\nBefore using the tool with a repository the state directory needs to be initialized:\n\n```\nusage: build_ogc_app init [-h] [-c CHECKOUT] source_repository [destination_directory]\n\npositional arguments:\n  source_repository     Directory or Git URL of application source files, default is current directory\n  destination_directory\n                        Directory where to check out source repository, default is a directory under the current subdirectory with same basename as the\n                        source_repository\n\noptions:\n  -h, --help            show this help message and exit\n  -c CHECKOUT, --checkout CHECKOUT\n                        Git hash, tag or branch to checkout from the source repository\n```\n\nThis can be accomplished with an existing clone of a repository or the tool can clone the repository locally for you. If no directory is supplied the tool will assume you would like to initialize the current directory. When working interatively it is suggested to change to the directory you are working with and use the script from there. This simplifies program usage and does not require you to use the `--state_directory` argument on each call. \n\nFor example to initialize an repository and use it locally:\n\n```\ngit clone https://github.com/unity-sds/unity-example-application.git\ncd unity-example-application\nbuild_ogc_app init\n```\n\nOr to have the tool clone and initialize the repository for you:\n\n```\nbuild_ogc_app init https://github.com/unity-sds/unity-example-application.git unity-example-application\ncd unity-example-application\n```\n\n### build_docker\n\nThe `build_docker` command does not require any additional arguments. It will utilize [app-pack-generator](https://github.com/unity-sds/app-pack-generator) and [repo2docker](https://github.com/jupyterhub/repo2docker), please see the documentation there for how to set up your repository for a successful build. The built Docker image name will be stored into `app_state.json` file in the state directory. This command requires the `init` step to have already been run.\n\n### push_docker\n\nThis command will push a Docker image built by the `build_docker` step to a remote Docker registry. It will then record the remote registry URL into the state directory for use by subsequent steps. The `push_docker` command has a required argument of either the URL of a remote Docker registry or a Dockerhub username. It is assumed you have already used `docker login` to initialze credentials. This command requires the `build_docker` step to have already been run.\n\n### build_cwl\n\nThe `build_cwl` will use [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create OGC compliant CWL files based on the parameterization of the Jupyter notebook in the target repository. Currently the Jupyter notebook is required to be named `process.ipynb`. Please see the [app-pack-generator](https://github.com/unity-sds/app-pack-generator) documentation for how to properly parameterize a notebook. The generated CWL files and application descriptor will be placed in the state directory. If the `push_docker ` step has not yet been run the CWL files will refer to the local Docker image tag instead a remote URL.\n\n### push_app_registry\n\nThe `push_app_registry` command pushes the generated CWL into a Dockstore application registry server. It requires the the URL to the Dockstore API as well as a token obtained through the Dockstore interface. The `build_cwl` step is required to have already been executed.\n\n```\nusage: build_ogc_app push_app_registry [-h] --api_url DOCKSTORE_API_URL --token DOCKSTORE_TOKEN\n\noptions:\n  -h, --help            show this help message and exit\n  --api_url DOCKSTORE_API_URL\n                        Dockstore API URL including the trailing api/ portion of the URL\n  --token DOCKSTORE_TOKEN\n                        Dockstore API token obtained from the My Services / Account page\n```\n\nThe API URL can be obtained from the Dockstore user interface by scrolling to the bottom and clicking the API link in the footer. It will be the portion of the URL up to the `/api` path. The API token is obtained by logging into the Dockstore, clocking on the username drop down in the top right corner then selecting the Account item. Copy the token from the Dockstore Account item.\n\n## Changelog\n\nSee our [CHANGELOG.md](CHANGELOG.md) for a history of our changes.\n\nSee our [releases page](https://github.com/unity-sds/unity-app-generator/releases) for our key versioned releases.\n\n## License\n\nSee our: [LICENSE](LICENSE.txt)\n",
    "bugtrack_url": null,
    "license": "Apache License",
    "summary": "Generates an OGC compliant Unity application package using the Unity app-pack-generator.",
    "version": "1.0.0",
    "project_urls": null,
    "split_keywords": [
        "unity-sds",
        " ogc",
        " packaging",
        " cwl",
        " jupyter"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5e5cf0c8e7389aca6ad930a6e736d501bebe1b175c914a9e175ddc8679a8b003",
                "md5": "13c00569d3c879592bbb804df02c4e4a",
                "sha256": "63dfc417db19fab313b455a5e5c303012044a55fb78f982a45a0d957bb858725"
            },
            "downloads": -1,
            "filename": "mdps_app_generator-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "13c00569d3c879592bbb804df02c4e4a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 14507,
            "upload_time": "2025-02-20T19:05:29",
            "upload_time_iso_8601": "2025-02-20T19:05:29.324058Z",
            "url": "https://files.pythonhosted.org/packages/5e/5c/f0c8e7389aca6ad930a6e736d501bebe1b175c914a9e175ddc8679a8b003/mdps_app_generator-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8711c3f3f8ba25d8e518eb117a7e1f98cca8b0cb29a6e062ce9b385c5672dfde",
                "md5": "703004cae502afdb1f4e432f56bc05fc",
                "sha256": "989b89c5099f12ce8d75576dbb56e679a2ef029d6d087d632350fc985ea33311"
            },
            "downloads": -1,
            "filename": "mdps_app_generator-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "703004cae502afdb1f4e432f56bc05fc",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 12812,
            "upload_time": "2025-02-20T19:05:30",
            "upload_time_iso_8601": "2025-02-20T19:05:30.835011Z",
            "url": "https://files.pythonhosted.org/packages/87/11/c3f3f8ba25d8e518eb117a7e1f98cca8b0cb29a6e062ce9b385c5672dfde/mdps_app_generator-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-20 19:05:30",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "mdps-app-generator"
}
        
Elapsed time: 0.40904s