clams-python 0.6.3__tar.gz → 1.0.0__tar.gz

{clams-python-0.6.3/clams_python.egg-info → clams-python-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: clams-python
-Version: 0.6.3
+Version: 1.0.0
 Summary: A collection of APIs to develop CLAMS app for python
 Home-page: https://clams.ai
 Author: Brandeis Lab for Linguistics and Computation

clams-python-1.0.0/VERSION

@@ -0,0 +1 @@
+1.0.0

{clams-python-0.6.3 → clams-python-1.0.0}/clams/__init__.py

@@ -2,17 +2,15 @@ import sys
 
 from mmif import __specver__
 
-from clams import source
 from clams import develop
+from clams import source
 from clams.app import *
 from clams.app import __all__ as app_all
 from clams.appmetadata import AppMetadata
 from clams.restify import Restifier
-from clams.source import WorkflowSource
-from clams.develop import CookieCutter
 from clams.ver import __version__
 
-__all__ = [AppMetadata, Restifier, WorkflowSource] + app_all
+__all__ = [AppMetadata, Restifier] + app_all
 version_template = "{} (based on MMIF spec: {})"
 
 
@@ -28,7 +26,11 @@ def prep_argparser():
     for subcmd_module in [source, develop]:
         subcmd_name = subcmd_module.__name__.rsplit('.')[-1]
         subcmd_parser = subcmd_module.prep_argparser(add_help=False)
-        subparsers.add_parser(subcmd_name, parents=[subcmd_parser], help=subcmd_module.prep_argparser.__doc__)
+        subparsers.add_parser(subcmd_name, parents=[subcmd_parser], 
+                              help=subcmd_module.describe_argparser()[0],
+                              description=subcmd_module.describe_argparser()[1],
+                              formatter_class=argparse.RawDescriptionHelpFormatter,
+                              )
     return parser
 
 

{clams-python-0.6.3 → clams-python-1.0.0}/clams/develop/__init__.py

@@ -3,30 +3,56 @@ import pathlib
 import re
 import shutil
 from string import Template
+from typing import List
 
 import clams
 
+available_recipes = {
+    'app': {
+        'description': 'Skeleton code for a CLAMS app',
+        'sourcedir': 'app',
+        'targetdir': '.',
+    },
+    'gha': {
+        'description': 'GtiHub Actions workflow files specific to `clamsproject` GitHub organization',
+        'sourcedir': 'gha',
+        'targetdir': '.github',
+    }
+}
+
 
 class CookieCutter(object):
     
-    def __init__(self, name:str, outdir:str, ghactions:bool=True):
+    def __init__(self, name: str, outdir: str, recipes: List[str]):
         self.rawname = name 
         self.name_tokens = self.tokenize_rawname()
         self.ourdir = pathlib.Path(outdir)
-        self.copy_gha = ghactions
+        if recipes:
+            self.recipes = recipes
+        else:
+            self.recipes = available_recipes.keys()
         
     def tokenize_rawname(self):
         word_pat = re.compile('[A-Z][a-z]+|[0-9A-Z]+(?=[A-Z][a-z])|[0-9A-Z]{2,}|[a-z0-9]{2,}|[a-zA-Z0-9]')
         words = [m.group(0).lower() for m in word_pat.finditer(self.rawname)]
-        if words[0] == 'app':
-            words.pop(0)
-        if words[-1] == 'app':
-            words.pop()
+        if len(words) > 1:
+            if words[0] == 'app':
+                words.pop(0)
+            if words[-1] == 'app':
+                words.pop()
         return words
     
     def bake(self):
-        src_dir = pathlib.Path(__file__).parent / 'templates' / 'app'
-        dst_dir = self.ourdir / self.rawname
+        print(f"Baking {self.recipes}")
+        for recipe in self.recipes:
+            src_dir = pathlib.Path(__file__).parent / 'templates' / available_recipes[recipe]['sourcedir']
+            dst_dir = self.ourdir / self.rawname / available_recipes[recipe]['targetdir']
+            if recipe == 'app':
+                self.bake_app(src_dir, dst_dir)
+            if recipe == 'gha':
+                self.bake_gha(src_dir, dst_dir)
+            
+    def bake_app(self, src_dir, dst_dir):
         excludes = {'__init__.py'}
         caps = [t.capitalize() for t in self.name_tokens]
         templating_vars = {
@@ -46,30 +72,35 @@ class CookieCutter(object):
                 tmpl_to_compile = Template(in_f.read())
                 compiled = tmpl_to_compile.safe_substitute(templating_vars)
                 out_f.write(compiled)
-        if self.copy_gha:
-            src_dir = pathlib.Path(__file__).parent / 'templates' / 'github'
-            dst_dir = dst_dir / '.github'
-            shutil.copytree(src_dir, dst_dir)
+        print(f"App skeleton code is copied to {self.rawname}")
+        print(f"  Checkout {self.rawname}/README.md for the next steps!")
+                
+    def bake_gha(self, src_dir, dst_dir):
+        shutil.copytree(src_dir, dst_dir, dirs_exist_ok=True)
+        print(f"GitHub Actions workflow files are copied to {self.rawname}/.github")
+        print(f"  Checkout {self.rawname}/.github/README.md for how they work!")
 
 
-def prep_argparser(**kwargs):
+def describe_argparser():
     """
-    provides CLI to create a skeleton code for app development.
+    returns two strings: one-line description of the argparser, and addition material, 
+    which will be shown in `clams --help` and `clams <subcmd> --help`, respectively.
     """
-    parser = argparse.ArgumentParser(**kwargs)
+    oneliner = 'provides CLI to create a skeleton code for app development'
+    additional = "Available recipes:\n"
+    for k, v in available_recipes.items():
+        additional += f"  - {k}: {v['description']}\n" 
+    return oneliner, oneliner + '\n\n' + additional
+    
+
+def prep_argparser(**kwargs):
+    parser = argparse.ArgumentParser(description=describe_argparser()[1], formatter_class=argparse.RawDescriptionHelpFormatter, **kwargs)
     parser.add_argument(
-        '-r', '--recipe', 
+        '-r', '--recipes', 
         action='store',
-        default='app',
-        choices=['app'],
-        help="Pick a recipe to use. Currently `app` is the only option, hence there's no need to use the flag at all."
-    )
-    parser.add_argument(
-        '--no-github-actions',
-        action='store_true', 
-        help='The cookiecutter by default assumes that the app codebase will be hosted on `github.com/clamsproejct`, '
-             'and add pre-shipped github actions for the `clamsproject` organization setup to the skeleton codebase. '
-             'Use this options to disable this behavior.'
+        nargs='+',
+        default=[],
+        help=f"Pick recipes to bake. DEFAULT: {list(available_recipes.keys())}"
     )
     parser.add_argument(
         '-n', '--name',
@@ -97,7 +128,7 @@ def prep_argparser(**kwargs):
 
 
 def main(args):
-    cutter = CookieCutter(name=args.name, outdir=args.parent_dir, ghactions=not args.no_github_actions)
+    cutter = CookieCutter(name=args.name, outdir=args.parent_dir, recipes=args.recipes)
     cutter.bake()
 
 if __name__ == '__main__':

{clams-python-0.6.3 → clams-python-1.0.0}/clams/develop/templates/app/README.md

@@ -7,21 +7,27 @@ This skeleton code is a scaffolding for Python-based CLAMS app development. Spec
 
 1. `app.py` and `metadata.py` to write the app 
 1. `requirements.txt` to specify python dependencies
-1. `.gitignore` file listing common ignored files
 1. `Containerfile` to containerize the app and specify system dependencies
+1. `.gitignore` and `.dorckrignore` files listing commonly ignored files
 1. an empty `LICENSE` file to replace with an actual license information of the app
 1. `CLAMS-generic-readme.md` file with basic instructions of app installation and execution
 1. This `README.md` file for additional information not specified in the generic readme file. 
-1. (optional) some GH actions workflow for issue/bug-report management
-1. (optional) a GH actions workflow to build and upload app images upon any push of a git tag
+1. A number of GitHub Actions workflows for issue/bug-report management 
+1. A GHA workflow to publish app images upon any push of a git tag
+   * **NOTE**: All GHA workflows included are designed to only work in repositories under `clamsproject` organization.
 
-Use the following section to document any additional information specific to this app. If your app works significantly 
-different from what's described in the generic readme file, be as specific as possible. 
+Before pushing your first commit, please make sure to delete this section of the document.
+
+Then use the following section to document any additional information specific to this app. If your app works significantly different from what's described in the generic readme file, be as specific as possible. 
 
 ---
 
 ## User instruction
 
+General user instruction for CLAMS apps is available at [CLAMS Apps documentation](https://apps.clams.ai/clamsapp/).
+
+Below is a list of additional information specific to this app.
+
 ### System requirments
 
 (Any system-level software required to run this app)

{clams-python-0.6.3 → clams-python-1.0.0}/clams/source/__init__.py

@@ -2,6 +2,7 @@ import argparse
 import itertools
 import json
 import sys
+import textwrap
 from os import path
 from typing import Union, Generator, List, Optional, Iterable
 
@@ -215,11 +216,20 @@ def generate_source_mmif(documents, prefix=None, **ignored):
     return pl.produce().serialize(pretty=True)
 
 
-def prep_argparser(**kwargs):
+def describe_argparser():
     """
-    provides CLI to create a "source" MMIF json. A source MMIF is a MMIF with a list of source documents but empty views. It can be used as a starting point for a CLAMS workflow. 
+    returns two strings: one-line description of the argparser, and addition material, 
+    which will be shown in `clams --help` and `clams <subcmd> --help`, respectively.
     """
-    parser = argparse.ArgumentParser(**kwargs)
+    oneliner = 'provides CLI to create a "source" MMIF json.'
+    additional = textwrap.dedent("""
+    A source MMIF is a MMIF with a list of source documents but empty views. 
+    It can be used as a starting point for a CLAMS workflow. """)
+    return oneliner, oneliner + '\n\n' + additional
+
+
+def prep_argparser(**kwargs):
+    parser = argparse.ArgumentParser(description=describe_argparser()[1], formatter_class=argparse.RawDescriptionHelpFormatter, **kwargs)
     parser.add_argument(
         'documents',
         default=None,

clams-python-1.0.0/clams/ver/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

{clams-python-0.6.3 → clams-python-1.0.0/clams_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: clams-python
-Version: 0.6.3
+Version: 1.0.0
 Summary: A collection of APIs to develop CLAMS app for python
 Home-page: https://clams.ai
 Author: Brandeis Lab for Linguistics and Computation

{clams-python-0.6.3 → clams-python-1.0.0}/clams_python.egg-info/SOURCES.txt

@@ -10,18 +10,17 @@ clams/appmetadata/__init__.py
 clams/develop/__init__.py
 clams/develop/templates/app/.dockerignore
 clams/develop/templates/app/.gitignore
-clams/develop/templates/app/CLAMS-generic-readme.md
 clams/develop/templates/app/Containerfile
 clams/develop/templates/app/LICENSE
 clams/develop/templates/app/README.md
 clams/develop/templates/app/app.py
 clams/develop/templates/app/metadata.py
 clams/develop/templates/app/requirements.txt
-clams/develop/templates/github/README.md
-clams/develop/templates/github/workflows/issue-apps-project.yml
-clams/develop/templates/github/workflows/issue-assign.yml
-clams/develop/templates/github/workflows/issue-close.yml
-clams/develop/templates/github/workflows/publish.yml
+clams/develop/templates/gha/README.md
+clams/develop/templates/gha/workflows/issue-apps-project.yml
+clams/develop/templates/gha/workflows/issue-assign.yml
+clams/develop/templates/gha/workflows/issue-close.yml
+clams/develop/templates/gha/workflows/publish.yml
 clams/restify/__init__.py
 clams/serve/__init__.py
 clams/source/__init__.py

{clams-python-0.6.3 → clams-python-1.0.0}/clams_python.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mmif-python==0.5.2
+mmif-python==1.0.0
 Flask>=2
 Flask-RESTful>=0.3.9
 gunicorn>=20

{clams-python-0.6.3 → clams-python-1.0.0}/requirements.txt

@@ -1,4 +1,4 @@
-mmif-python==0.5.2
+mmif-python==1.0.0
 
 Flask>=2
 Flask-RESTful>=0.3.9

clams-python-0.6.3/VERSION

@@ -1 +0,0 @@
-0.6.3

clams-python-0.6.3/clams/develop/templates/app/CLAMS-generic-readme.md

@@ -1,69 +0,0 @@
-# CLAMS App
-
-This document provides general instructions for installing and using CLAMS apps. 
-App developers may provide additional information specific to their app, 
-hence it's advised also to look up the app website (or code repository) to get the additional information. 
-
-## Requirements 
-
-Generally, an CLAMS app requires 
-
-- Python3 with the `clams-python` module installed; to run the app locally. 
-- `docker` or `podman`; to run the app in a container (as an HTTP server).
-- An HTTP client utility (such as `curl`); to invoke and execute analysis.
-
-For Python dependencies, usually apps come with `requirements.txt` files that list up the Python library. 
-However, there could be other non-Python software/library that are required by the app.
-
-## Installation
-
-Currently, CLAMS apps available on the CLAMS app-directory are all open-source projects and are distributed as
-
-1. source code downloadable from code repository
-2. pre-built container image 
-
-Please visit [the app-directory](https://github.com/clamsproject/clams-apps) to see which apps are available and where you can download them.
- 
-In most cases, you can "install" a CLAMS app by either
-1. downloading source code from the app code repository and manually building a container image
-2. downloading pre-built container image directly
-
-## Building container image
-
-From the project directory, run the following in your terminal to build an image from the included container specification file.
-
-(Assuming you are using `docker` as your container manager)
-
-```bash
-docker build . -f Containerfile -t <app_name>
-```
-
-Alternatively, the app maybe already be available on a container registry.
-
-``` bash 
-docker pull <app_name>
-```
-
-## Running the image
-
-Then to create a container using that image, run:
-
-```bash
-docker run -v /path/to/data/directory:/data -p <port>:5000 <app_name>
-```
-
-where `/path/to/data/directory` is the local location of your media files or MMIF objects and <port> is the *host* port number you want your container to be listening to. 
-The HTTP inside the container will be listening to 5000 by default. 
-
-## Invoking the app
-Once the app is running as an HTTP server, to invoke the app and get automatic annotations, simply send a POST request to the app with a MMIF input as request body.
-
-MMIF input files can be obtained from outputs of other CLAMS apps, or you can create an empty MMIF only with source media locations using `clams source` command. See the help message for a more detailed instructions. 
-(Make sure you have installed [`clams-python` package](https://pypi.org/project/clams-python/) version from PyPI.)
-
-```bash
-pip install clams-python
-clams source --help
-```
-
-

clams-python-0.6.3/clams/ver/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.6.3"