gams-frog 0.3.0__tar.gz

gams_frog-0.3.0/.gitignore

@@ -0,0 +1,15 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# venv
+.venv
+
+output/*
+views/*
+.idea/*
+.python-version

gams_frog-0.3.0/.gitlab-ci.yml

@@ -0,0 +1,57 @@
+variables:
+    UV_VERSION: 0.5
+    PYTHON_BASE_VERSION: 3.12
+    BASE_LAYER: bookworm-slim
+
+stages:
+  - test
+  - lint
+  - build
+  - publish
+
+# A hidden job template that can be used by different Python versions
+.test-template:
+  stage: test
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_BASE_VERSION-$BASE_LAYER
+  script:
+    - echo "uv environment version"
+    - uv --version
+    - echo "Pinning ${PYTHON_VERSION}"
+    - uv python pin ${PYTHON_VERSION}
+    - uv sync
+    - echo "Using python version:"
+    - python --version
+    - echo "Running tests with uv"
+    - uv run pytest tests
+
+# Specific jobs for Python versions
+test-py_3.12:
+  extends: .test-template
+  variables:
+    PYTHON_VERSION: "3.12"
+
+lint:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_BASE_VERSION-$BASE_LAYER
+  script:
+    - echo "uv environment version"
+    - uv --version
+    - echo "Using python version:"
+    - python --version
+    - echo "Running uv check with ruff"
+    - uv run ruff check src
+
+build:
+  stage: build
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_BASE_VERSION-$BASE_LAYER
+  script:
+    uv build
+
+publish-pypi:
+  stage: publish
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_BASE_VERSION-$BASE_LAYER
+  script:
+    - uv build
+    - uv publish --token $PYPI_TOKEN
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

gams_frog-0.3.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.3]
+
+### Changed
+
+- renamed tool to gams-frog (from pollin-tool)
+
+## [0.0.2] - 13.04.2026 [YANKED]
+
+### Added
+
+- cli commands now default for gams-frog.toml to the current working directory of gams-frog
+- added --version command
+- corrected readme (for deployed tool)
+
+## [0.0.1] - 13.04.2026 [YANKED]
+
+### Added
+
+- release of initial beta version of the software
+- core features with SSR rendering with GAMS5

gams_frog-0.3.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian David Schiller-Stoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gams_frog-0.3.0/Makefile

@@ -0,0 +1,16 @@
+# make test, coverage, documentation, etc
+SHELL := /bin/bash
+
+.PHONY: all test clean build
+
+all: test lint build
+
+test:
+	@uv run pytest tests
+
+lint:
+	@uv run ruff check src
+
+build:
+	@uv build
+

gams_frog-0.3.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: gams-frog
+Version: 0.3.0
+Summary: CLI tool for frontend generation for GAMS5 projects
+Project-URL: Repository, https://zimlab.uni-graz.at/gams5/production/postprocessing/gams-frog
+Author-email: Sebastian David Schiller-Stoff <sebastian.stoff@uni-graz.at>
+License: MIT
+License-File: LICENSE.md
+Keywords: digital-humanities,gams,jinja2,static-site-generator
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: click>=8.3.1
+Requires-Dist: jinja2==3.1.6
+Requires-Dist: requests>=2.32.4
+Requires-Dist: watchdog>=6.0.0
+Description-Content-Type: text/markdown
+
+# gams-frog
+
+CLI tool that generates frontends for GAMS5 projects.
+Supplies a development workflow for GAMS5-based web projects.
+
+Meant as replacement for the gams3 "gamsdev" development workflow.
+
+## Quickstart
+
+1. Setup project files for gams-frog
+
+2. Install gams-frog itself
+
+```sh
+
+# 1. install uv
+# mac might need brew to install uv
+
+# 2. install gams_frog via 
+# optionally specifiy version tag
+uv tool install gams_frog
+
+# verify installation via
+frog --version
+
+# 3. use the gams_frog
+cd ./my/working/directory
+frog dev # will use the gams_frog.toml from the current working dir
+# alternatively specifiy a path
+frog dev "C:\path\to\project"
+# check for basic commands
+frog 
+
+```
+
+## Basic usage
+
+1. Have a running GAM5-API (OR external)
+2. Clone or init project files
+3. UV setup (install via pypi or clone via git)
+
+
+```sh
+# 01. Setup project files from templates: https://zimlab.uni-graz.at/gams5/projects/project_template/gams-www
+# 01b. Install uv (python package)
+
+# 02a. Install via pypi
+# 02a. uv install / pip install
+
+# 02b. Clone gams_frog
+# 02b. uv sync (uv procedure)
+# 02b. Start virtual environment (venv)
+
+# 03. Configure gams_frog via config file (gams_frog.toml) in template project folder
+
+# (point to project folder with config file)
+frog dev "C:\path\to\project"
+
+# for production use
+frog build "C:\path\to\project"
+
+```
+
+### Staging
+
+```sh
+frog stage "/path/to/project"
+
+```
+
+
+### Production
+
+```sh
+# use build command to generate the production files
+frog build "/path/to/project"
+
+```
+
+
+### Deployment
+
+- use the -d flag to deploy to staging or production environment
+
+```sh
+# staging deployment
+frog stage "/path/to/project" -d
+
+# production deployment
+frog build "/path/to/project" -d
+
+
+```
+
+
+## Development
+
+### Release
+
+1. Increment version in pyproject.toml in feature branch (merging into develop):
+    - make sure version follow vd.d.d pattern 
+2. Merge changes to develop -> main
+3. Create release on the gitlab webclient (from main branch) with new git tag that must be the same as in the pyproject.toml!
+    - e.g. v0.1.1
+    - create the release from the main branch!
+    - gitlab will autodeploy the new version to pypi

gams_frog-0.3.0/README.md

@@ -0,0 +1,106 @@
+# gams-frog
+
+CLI tool that generates frontends for GAMS5 projects.
+Supplies a development workflow for GAMS5-based web projects.
+
+Meant as replacement for the gams3 "gamsdev" development workflow.
+
+## Quickstart
+
+1. Setup project files for gams-frog
+
+2. Install gams-frog itself
+
+```sh
+
+# 1. install uv
+# mac might need brew to install uv
+
+# 2. install gams_frog via 
+# optionally specifiy version tag
+uv tool install gams_frog
+
+# verify installation via
+frog --version
+
+# 3. use the gams_frog
+cd ./my/working/directory
+frog dev # will use the gams_frog.toml from the current working dir
+# alternatively specifiy a path
+frog dev "C:\path\to\project"
+# check for basic commands
+frog 
+
+```
+
+## Basic usage
+
+1. Have a running GAM5-API (OR external)
+2. Clone or init project files
+3. UV setup (install via pypi or clone via git)
+
+
+```sh
+# 01. Setup project files from templates: https://zimlab.uni-graz.at/gams5/projects/project_template/gams-www
+# 01b. Install uv (python package)
+
+# 02a. Install via pypi
+# 02a. uv install / pip install
+
+# 02b. Clone gams_frog
+# 02b. uv sync (uv procedure)
+# 02b. Start virtual environment (venv)
+
+# 03. Configure gams_frog via config file (gams_frog.toml) in template project folder
+
+# (point to project folder with config file)
+frog dev "C:\path\to\project"
+
+# for production use
+frog build "C:\path\to\project"
+
+```
+
+### Staging
+
+```sh
+frog stage "/path/to/project"
+
+```
+
+
+### Production
+
+```sh
+# use build command to generate the production files
+frog build "/path/to/project"
+
+```
+
+
+### Deployment
+
+- use the -d flag to deploy to staging or production environment
+
+```sh
+# staging deployment
+frog stage "/path/to/project" -d
+
+# production deployment
+frog build "/path/to/project" -d
+
+
+```
+
+
+## Development
+
+### Release
+
+1. Increment version in pyproject.toml in feature branch (merging into develop):
+    - make sure version follow vd.d.d pattern 
+2. Merge changes to develop -> main
+3. Create release on the gitlab webclient (from main branch) with new git tag that must be the same as in the pyproject.toml!
+    - e.g. v0.1.1
+    - create the release from the main branch!
+    - gitlab will autodeploy the new version to pypi

gams_frog-0.3.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "gams-frog"
+version = "v0.3.0"
+description = "CLI tool for frontend generation for GAMS5 projects"
+authors = [
+    { name = "Sebastian David Schiller-Stoff", email = "sebastian.stoff@uni-graz.at" }
+]
+license = { text = "MIT" }
+dependencies = [
+    "jinja2==3.1.6",
+    "click>=8.3.1",
+    "watchdog>=6.0.0",
+    "aiohttp>=3.13.3",
+    "requests>=2.32.4"
+]
+readme = "README.md"
+requires-python = ">= 3.12"
+keywords = ["gams", "static-site-generator", "digital-humanities", "jinja2"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Repository = "https://zimlab.uni-graz.at/gams5/production/postprocessing/gams-frog"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gams_frog"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "ruff>=0.14.0"
+]
+
+[project.scripts]
+frog = "gams_frog.cli:cli"

gams_frog-0.3.0/src/gams_frog/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from gams_frog!"

gams_frog-0.3.0/src/gams_frog/cli.py

@@ -0,0 +1,229 @@
+import logging
+import sys
+
+import click
+import multiprocessing
+
+from importlib.metadata import version, PackageNotFoundError
+# makes sure that the version is set correctly
+try:
+    __version__ = version("gams_frog-tool")
+except PackageNotFoundError:
+    __version__ = "dev"
+
+from gams_frog.deploy.GamsAuthClient import GamsAuthClient
+from gams_frog.ssr.watch.ApplicationViewFileEventController import ApplicationViewFileEventController
+from gams_frog.ssr.init.ApplicationContext import ApplicationContext
+from gams_frog.ssr.load.ApplicationDataLoader import ApplicationDataLoader
+from gams_frog.ssr.watch.ApplicationViewFileWatcher import ApplicationViewFileWatcher
+from gams_frog.ssr.watch.ApplicationWebServer import ApplicationWebServer
+from gams_frog.ssr.init.AppInitializer import AppInitializer
+from gams_frog.validation.JinjaTemplateValidator import JinjaTemplateValidator
+from gams_frog.validation.StaticFileValidator import StaticFileValidator
+
+# global application context
+app_context = ApplicationContext()
+
+def run_validation_or_exit(context: ApplicationContext):
+    # 1. Validate Templates (AST)
+    template_validator = JinjaTemplateValidator(context)
+    templates_ok = template_validator.validate()
+
+    # 2. Validate Static Files (Regex)
+    static_validator = StaticFileValidator(context)
+    static_ok = static_validator.validate()
+
+    if not (templates_ok and static_ok):
+        logging.error("Build aborted due to quality gate violations.")
+        sys.exit(1)
+
+
+def run_deploy(context: ApplicationContext, username: str | None, password: str | None):
+    """
+    Performs authentication and deployment to the GAMS5 API.
+
+    :param context: The application context
+    :param username: GAMS API username (prompted if not provided)
+    :param password: GAMS API password (prompted if not provided)
+    """
+    from gams_frog.deploy.DeployService import DeployService
+
+    mode = context.get_config().mode
+    target_host = context.get_config().gams_host
+
+    # Safety confirmation for production deployments
+    if mode == "build":
+        click.echo("\n*** PRODUCTION DEPLOYMENT ***")
+        click.echo(f"Target: {target_host}")
+        click.echo(f"Project: {context.get_config().project}")
+        if not click.confirm("Deploy to PRODUCTION environment?", default=False):
+            click.echo("Deployment cancelled.")
+            return
+
+    # Prompt for credentials if not provided via options
+    if not username:
+        username = click.prompt("GAMS API username")
+    if not password:
+        password = click.prompt("GAMS API password", hide_input=True)
+
+    # Authenticate
+    logging.info(f"Authenticating with GAMS API at {target_host}...")
+    auth_gams_client = GamsAuthClient(target_host)
+    try:
+        from gams_frog.deploy.AuthorizationService import AuthorizationService
+        # TODO using a separte client seems weird
+        auth_service = AuthorizationService(auth_gams_client)
+        auth_service.login(username=username, password=password)
+    except PermissionError as e:
+        logging.error(f"Authentication failed: {e}")
+        sys.exit(1)
+    except Exception as e:
+        logging.error(f"Authentication error: {e}")
+        sys.exit(1)
+
+    # Deploy
+    try:
+        deploy_service = DeployService(context, auth_gams_client)
+        result = deploy_service.deploy()
+        click.echo("\nDeployment successful!")
+        click.echo(f"  Project:    {result.get('projectAbbr', 'N/A')}")
+        click.echo(f"  Files:      {result.get('fileCount', 'N/A')}")
+        click.echo(f"  Total size: {result.get('totalSize', 'N/A')} bytes")
+        click.echo(f"  Deployed at: {result.get('deployedAt', 'N/A')}")
+    except (FileNotFoundError, ValueError) as e:
+        logging.error(f"Deployment failed: {e}")
+        sys.exit(1)
+    except (ConnectionError, PermissionError) as e:
+        logging.error(f"Deployment failed: {e}")
+        sys.exit(1)
+
+
+@click.group()
+@click.version_option(version=version("gams_frog"), prog_name="gams_frog")
+@click.option("--log", "-l", default="INFO", help="log level, default is INFO")
+def cli(log: str):
+    """
+    Init command / start routine of application
+    Sets up the application context for the entire application.
+    """
+    logging.basicConfig( encoding='utf-8', level=logging.getLevelName(log))
+
+@cli.command(name="stage", help="Builds output files once with staging configuration.")
+@click.argument("directory", default=".", required=False)
+@click.option("--deploy", "-d", is_flag=True, default=False, help="Deploy the built files to the staging GAMS API after build.")
+@click.option("--username", "-u", default=None, help="GAMS API username for deployment.")
+@click.option("--password", "-p", default=None, help="GAMS API password for deployment.")
+def stage(directory: str, deploy: bool, username: str, password: str):
+    """
+    Builds the static site generator output files with staging config.
+    Use --deploy to upload the result to the staging GAMS API.
+    """
+
+    # setting up the application context
+    (AppInitializer(app_context)
+     .configure(
+        directory=directory,
+        mode="stage"
+    )
+     .init_context_beans()
+     .setup()
+     )
+
+    # validate template files first
+    run_validation_or_exit(app_context)
+
+    # encapsulates loading of project data and digital objects
+    (ApplicationDataLoader(app_context)
+        .load())
+
+    # render all views (and handle related files etc.)
+    (ApplicationViewFileEventController(app_context)
+        .render_views())
+
+    # deploy if requested
+    if deploy:
+        run_deploy(app_context, username, password)
+
+
+@cli.command(name="build", help="Builds production output files.")
+@click.argument("directory", default=".", required=False)
+@click.option("--deploy", "-d", is_flag=True, default=False, help="Deploy the built files to the production GAMS API after build.")
+@click.option("--username", "-u", default=None, help="GAMS API username for deployment.")
+@click.option("--password", "-p", default=None, help="GAMS API password for deployment.")
+def build(directory: str, deploy: bool, username: str, password: str):
+    """
+    Builds the static site generator production output files.
+    Use --deploy to upload the result to the production GAMS API.
+    """
+
+    # setting up the application context
+    (AppInitializer(app_context)
+     .configure(
+        directory=directory,
+        mode="build"
+    )
+     .init_context_beans()
+     .setup()
+     )
+
+    # validate template files first
+    run_validation_or_exit(app_context)
+
+    # encapsulates loading of project data and digital objects
+    (ApplicationDataLoader(app_context)
+        .load())
+
+    # render all views (and handle related files etc.)
+    (ApplicationViewFileEventController(app_context)
+        .render_views())
+
+    # deploy if requested
+    if deploy:
+        run_deploy(app_context, username, password)
+
+
+@cli.command(name="dev", help="Starts the development process of the gams_frog tool.")
+@click.argument("directory", default=".", required=False)
+@click.option("--port", "-p", default=18090, help="The port to run the development server on")
+def dev(directory: str, port: int):
+    """
+    Starts the static site generator (web server with rendering of views and initial data loading etc.)
+    """
+
+    # setting up the application context
+    (AppInitializer(app_context)
+     .configure(
+        directory=directory,
+        mode="dev"
+    )
+     .init_context_beans()
+     .setup()
+     )
+
+    # first run validation
+    run_validation_or_exit(app_context)
+
+    # encapsulates loading of project data and digital objects
+    (ApplicationDataLoader(app_context)
+        .load())
+
+    web_dir = app_context.get_config().public_dir
+    dev_server_process = multiprocessing.Process(target=ApplicationWebServer.start, args=(web_dir, port,))
+
+    try:
+        logging.info(f"*** Starting web server at port {port}")
+        dev_server_process.start()
+        logging.info("*** Starting view file watcher now")
+        ApplicationViewFileWatcher.start(
+            app_context
+        )
+        dev_server_process.join()
+    except KeyboardInterrupt:
+        logging.info("Keyboard interrupt received. Stopping processes")
+        dev_server_process.terminate()
+        dev_server_process.join()
+
+
+cli.add_command(dev)
+cli.add_command(build)
+cli.add_command(stage)