cave-cli 3.5.0__py3-none-any.whl

cave_cli/utils/subprocess.py

@@ -0,0 +1,129 @@
+import subprocess
+import sys
+
+from cave_cli.utils.logger import logger
+
+
+def run(
+    args: list[str],
+    capture: bool = True,
+    check: bool = False,
+    cwd: str | None = None,
+    inherit_io: bool = False,
+) -> subprocess.CompletedProcess:
+    """
+    Usage:
+
+    - Runs a subprocess command with standardized handling
+
+    Requires:
+
+    - ``args``:
+        - Type: list[str]
+        - What: The command and arguments to run
+
+    Optional:
+
+    - ``capture``:
+        - Type: bool
+        - What: Whether to capture stdout/stderr
+        - Default: True
+
+    - ``check``:
+        - Type: bool
+        - What: Whether to raise on non-zero exit
+        - Default: False
+
+    - ``cwd``:
+        - Type: str | None
+        - What: Working directory for the command
+        - Default: None
+
+    - ``inherit_io``:
+        - Type: bool
+        - What: Whether to pass through stdin/stdout/stderr for
+          interactive processes
+        - Default: False
+
+    Returns:
+
+    - ``result``:
+        - Type: subprocess.CompletedProcess
+        - What: The completed process result
+    """
+    kwargs: dict = {"cwd": cwd}
+    if inherit_io:
+        kwargs["stdin"] = sys.stdin
+        kwargs["stdout"] = sys.stdout
+        kwargs["stderr"] = sys.stderr
+    elif capture:
+        kwargs["stdout"] = subprocess.PIPE
+        kwargs["stderr"] = subprocess.PIPE
+        kwargs["text"] = True
+    return subprocess.run(args, check=check, **kwargs)
+
+
+def run_and_log(
+    args: list[str],
+    level: str = "DEBUG",
+    cwd: str | None = None,
+) -> subprocess.CompletedProcess:
+    """
+    Usage:
+
+    - Runs a subprocess and pipes each output line through the logger
+
+    Requires:
+
+    - ``args``:
+        - Type: list[str]
+        - What: The command and arguments to run
+
+    Optional:
+
+    - ``level``:
+        - Type: str
+        - What: Log level for output lines
+        - Default: "DEBUG"
+
+    - ``cwd``:
+        - Type: str | None
+        - What: Working directory for the command
+        - Default: None
+
+    Returns:
+
+    - ``result``:
+        - Type: subprocess.CompletedProcess
+        - What: The completed process result
+    """
+    result = run(args, cwd=cwd, capture=True)
+    log_fn = getattr(logger, level.lower(), logger.debug)
+    if result.stdout:
+        for line in result.stdout.strip().splitlines():
+            log_fn(line)
+    if result.stderr:
+        for line in result.stderr.strip().splitlines():
+            log_fn(line)
+    return result
+
+
+def version_tuple(v: str) -> tuple[int, ...]:
+    """
+    Usage:
+
+    - Parses a version string into a comparable tuple of integers
+
+    Requires:
+
+    - ``v``:
+        - Type: str
+        - What: A version string like "23.0.6"
+
+    Returns:
+
+    - ``parts``:
+        - Type: tuple[int, ...]
+        - What: A tuple of integers for comparison
+    """
+    return tuple(int(x) for x in v.split(".") if x.isdigit())

cave_cli/utils/sync.py

@@ -0,0 +1,89 @@
+import fnmatch
+import os
+import shutil
+from pathlib import Path
+
+from cave_cli.utils.logger import logger
+
+
+def sync_files(
+    source: str,
+    dest: str,
+    includes: list[str] | None = None,
+    excludes: list[str] | None = None,
+) -> None:
+    """
+    Usage:
+
+    - Syncs files from a source directory to a destination directory
+
+    Requires:
+
+    - ``source``:
+        - Type: str
+        - What: The source directory to copy from
+
+    - ``dest``:
+        - Type: str
+        - What: The destination directory to copy to
+
+    Optional:
+
+    - ``includes``:
+        - Type: list[str] | None
+        - What: Patterns for files that should always be included
+          (overrides excludes)
+        - Default: None
+
+    - ``excludes``:
+        - Type: list[str] | None
+        - What: Patterns for files that should be excluded
+        - Default: None
+
+    Notes:
+
+    - Always excludes ``.git``
+    - Include patterns override exclude patterns (matching rsync semantics)
+    - Uses ``shutil.copytree`` with ``dirs_exist_ok=True`` for merge behavior
+    """
+    clean_includes = [strip_quotes(p) for p in (includes or [])]
+    clean_excludes = [strip_quotes(p) for p in (excludes or [])]
+    clean_excludes.append(".git")
+
+    def ignore_fn(directory: str, contents: list[str]) -> set[str]:
+        rel_dir = os.path.relpath(directory, source)
+        ignored: set[str] = set()
+        for name in contents:
+            if rel_dir == ".":
+                rel_path = name
+            else:
+                rel_path = os.path.join(rel_dir, name)
+            if matches_any(rel_path, name, clean_includes):
+                continue
+            if matches_any(rel_path, name, clean_excludes):
+                ignored.add(name)
+        return ignored
+
+    shutil.copytree(
+        source, dest, ignore=ignore_fn, dirs_exist_ok=True
+    )
+
+
+def strip_quotes(pattern: str) -> str:
+    pattern = pattern.strip()
+    if (pattern.startswith("'") and pattern.endswith("'")) or (
+        pattern.startswith('"') and pattern.endswith('"')
+    ):
+        return pattern[1:-1]
+    return pattern
+
+
+def matches_any(
+    rel_path: str, name: str, patterns: list[str]
+) -> bool:
+    for pattern in patterns:
+        if fnmatch.fnmatch(name, pattern):
+            return True
+        if fnmatch.fnmatch(rel_path, pattern):
+            return True
+    return False

cave_cli/utils/validate.py

@@ -0,0 +1,218 @@
+import os
+import sys
+from pathlib import Path
+
+from cave_cli.utils.constants import (
+    CHAR_LINE,
+    CURRENT_ENV_VARIABLES,
+    RETIRED_ENV_VARIABLES,
+    INVALID_NAME_END_RE,
+    INVALID_NAME_HYPHEN_UNDER_RE,
+    INVALID_NAME_START_RE,
+    INVALID_NAME_UNDER_HYPHEN_RE,
+    VALID_NAME_RE,
+)
+from cave_cli.utils.logger import logger
+
+
+def validate_app_name(name: str) -> str | None:
+    """
+    Usage:
+
+    - Validates a CAVE app name against naming rules
+
+    Requires:
+
+    - ``name``:
+        - Type: str
+        - What: The app name to validate
+
+    Returns:
+
+    - ``error``:
+        - Type: str | None
+        - What: An error message if invalid, or None if valid
+    """
+    if len(name) < 2 or len(name) > 255:
+        return "The app name needs to be two to 255 characters"
+    if not VALID_NAME_RE.match(name):
+        return (
+            "The app name can only contain lowercase letters, "
+            "numbers, hyphens (-), and underscores (_)"
+        )
+    if INVALID_NAME_START_RE.match(name):
+        return (
+            "The app name cannot start with a hyphen (-) "
+            "or an underscore (_)"
+        )
+    if INVALID_NAME_END_RE.match(name):
+        return (
+            "The app name cannot end with a hyphen (-) "
+            "or an underscore (_)"
+        )
+    if INVALID_NAME_HYPHEN_UNDER_RE.search(name):
+        return (
+            "The app name cannot contain a hyphen (-) "
+            "followed by an underscore (_)"
+        )
+    if INVALID_NAME_UNDER_HYPHEN_RE.search(name):
+        return (
+            "The app name cannot contain an underscore (_) "
+            "followed by a hyphen (-)"
+        )
+    return None
+
+
+def validate_app_dir(path: str) -> list[str]:
+    """
+    Usage:
+
+    - Checks if a directory is a valid CAVE app directory
+
+    Requires:
+
+    - ``path``:
+        - Type: str
+        - What: The path to validate
+
+    Returns:
+
+    - ``errors``:
+        - Type: list[str]
+        - What: A list of error messages. Empty if the directory is valid.
+    """
+    p = Path(path)
+    errors: list[str] = []
+
+    if not (p / "manage.py").is_file() or not (p / "cave_core").is_dir():
+        return ["Not a CAVE app directory"]
+
+    for folder in ("cave_api", "cave_app", "cave_core"):
+        if not (p / folder).is_dir():
+            errors.append(
+                f"The folder '{folder}' is missing "
+                "in the root project directory."
+            )
+
+    for file in (".env", "manage.py", "requirements.txt", "Dockerfile"):
+        if not (p / file).is_file():
+            errors.append(
+                f"The file '{file}' is missing "
+                "in the root project directory."
+            )
+
+    env_path = p / ".env"
+    if env_path.is_file():
+        from cave_cli.utils.env import parse_env
+
+        env_vars = parse_env(str(env_path))
+        for var in CURRENT_ENV_VARIABLES:
+            if var not in env_vars:
+                errors.append(
+                    f"The env variable '{var}' is missing "
+                    "from the '.env' file."
+                )
+        for var in RETIRED_ENV_VARIABLES:
+            if var in env_vars:
+                errors.append(
+                    f"The env variable '{var}' is retired and "
+                    "should be removed from the '.env' file."
+                )
+
+    if not (p / "Dockerfile").is_file():
+        errors.append("No Dockerfile found in current directory.")
+
+    return errors
+
+
+def find_app_dir(start: str | None = None) -> str:
+    """
+    Usage:
+
+    - Walks up the directory tree to find a valid CAVE app directory
+
+    Optional:
+
+    - ``start``:
+        - Type: str | None
+        - What: The starting directory to search from
+        - Default: None (uses current working directory)
+
+    Returns:
+
+    - ``path``:
+        - Type: str
+        - What: The absolute path to the CAVE app directory
+    """
+    path = Path(start or os.getcwd()).resolve()
+    while True:
+        errors = validate_app_dir(str(path))
+        if not errors:
+            return str(path)
+        parent = path.parent
+        if parent == path:
+            for err in errors:
+                logger.error(err)
+            logger.error("Ensure you are in a valid CAVE app directory")
+            sys.exit(1)
+        path = parent
+
+
+def get_app(start: str | None = None) -> tuple[str, str]:
+    """
+    Usage:
+
+    - Finds the CAVE app directory and returns its path and name
+
+    Optional:
+
+    - ``start``:
+        - Type: str | None
+        - What: The starting directory to search from
+        - Default: None (uses current working directory)
+
+    Returns:
+
+    - ``app_dir``:
+        - Type: str
+        - What: The absolute path to the CAVE app directory
+
+    - ``app_name``:
+        - Type: str
+        - What: The base name of the app directory
+    """
+    app_dir = find_app_dir(start)
+    app_name = Path(app_dir).resolve().name
+    return app_dir, app_name
+
+
+def confirm_action(message: str, auto_yes: bool = False) -> None:
+    """
+    Usage:
+
+    - Prompts the user for confirmation before proceeding
+
+    Requires:
+
+    - ``message``:
+        - Type: str
+        - What: The action description to display
+
+    Optional:
+
+    - ``auto_yes``:
+        - Type: bool
+        - What: If True, bypasses the prompt and continues
+        - Default: False
+    """
+    if auto_yes:
+        return
+    try:
+        response = input(f"{message}. Would you like to continue? [y/N] ")
+    except (EOFError, KeyboardInterrupt):
+        print()
+        logger.error("Operation canceled.")
+        sys.exit(1)
+    if response.strip().lower() not in ("y", "yes"):
+        logger.error("Operation canceled.")
+        sys.exit(1)

cave_cli-3.5.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: cave_cli
+Version: 3.5.0
+Summary: CLI for creating and managing Docker-based CAVE web applications.
+Author-email: MIT-CAVE <cave-contact@mit.edu>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/MIT-CAVE/cave_cli
+Project-URL: Bug Tracker, https://github.com/MIT-CAVE/cave_cli/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Dynamic: license-file
+
+# CAVE CLI
+
+A cross-platform CLI for creating and managing Docker-based CAVE web applications.
+
+Developed by [MIT-CAVE](https://cave.mit.edu/) (Center for Transportation & Logistics). Licensed under Apache 2.0.
+
+## Prerequisites
+
+- [Python](https://www.python.org/downloads/) 3.11+
+- [Docker](https://docs.docker.com/get-docker/) 23.0.6+
+- [Git](https://git-scm.com/)
+
+<details>
+<summary>Ubuntu</summary>
+
+```sh
+# Install Docker
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh ./get-docker.sh
+# Add the current user to the docker group
+dockerd-rootless-setuptool.sh install
+# Make sure it works outside of sudo
+docker run hello-world
+```
+
+</details>
+<details>
+<summary>macOS</summary>
+
+- Install Docker Desktop: https://docs.docker.com/docker-for-mac/install/
+
+</details>
+<details>
+<summary>Windows</summary>
+
+- Install Docker Desktop for WSL: https://docs.docker.com/desktop/wsl/
+- Install WSL2 with Ubuntu: https://learn.microsoft.com/en-us/windows/wsl/install
+- Open your WSL Ubuntu terminal for all `cave` commands
+
+</details>
+
+## Installation
+
+```sh
+pip install git+https://github.com/MIT-CAVE/cave_cli.git
+```
+
+Or with [pipx](https://pipx.pypa.io/) (recommended for CLI tools):
+
+```sh
+pipx install git+https://github.com/MIT-CAVE/cave_cli.git
+```
+
+Verify the installation:
+
+```sh
+cave --version
+```
+
+## Quick Start
+
+```sh
+cave create my_app
+cd my_app
+cave run
+# Open http://localhost:8000/ in your browser
+```
+
+## CLI Commands
+
+```sh
+cave --help
+```
+
+### Core Commands
+
+| Command | Description |
+|---|---|
+| `cave create <name>` | Create a new CAVE app from the template repository |
+| `cave run` | Build Docker image and run the app |
+
+### Peripheral Commands
+
+| Command | Description |
+|---|---|
+| `cave reset` | Remove containers/volumes and rebuild from scratch |
+| `cave upgrade` | Upgrade app files from the upstream template |
+| `cave sync --url <url>` | Merge files from another repository into the app |
+| `cave test` | Run tests in `cave_api/tests/` |
+| `cave prettify` | Format code with autoflake and black |
+| `cave purge <path>` | Remove an app and all its Docker resources |
+
+### Utility Commands
+
+| Command | Description |
+|---|---|
+| `cave list` | List running CAVE apps |
+| `cave kill` | Stop Docker containers for an app |
+| `cave list-versions` | List available CAVE app versions |
+| `cave update` | Update the CAVE CLI itself |
+| `cave uninstall` | Remove the CAVE CLI |
+| `cave version` | Print version information |
+
+### Global Flags
+
+| Flag | Description |
+|---|---|
+| `-v`, `--verbose` | Enable verbose (DEBUG) logging output |
+| `--loglevel LEVEL` | Set log level: DEBUG, INFO, WARN, ERROR, SILENT |
+| `-y`, `--yes` | Automatically answer confirmation prompts with yes |
+
+## Updating
+
+```sh
+pip install --upgrade git+https://github.com/MIT-CAVE/cave_cli.git
+```
+
+Or:
+
+```sh
+cave update
+```
+
+## License Notice
+
+Copyright 2023 Massachusetts Institute of Technology (MIT), Center for Transportation & Logistics (CTL)
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

cave_cli-3.5.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+cave_cli/__init__.py,sha256=87INpPcp1F7_PqWBWVyWIJMFP4m5wqP3zwTouzbVx68,74
+cave_cli/cli.py,sha256=4rBrxNCWfLIZsu-DzxKL-2XWU8UCEXz3x59W1mUKW2w,14106
+cave_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cave_cli/commands/create.py,sha256=5RrZd8GGQOJiajNlTYnUYl68B40Pu7XTm7p3u8Rvhqo,5192
+cave_cli/commands/kill.py,sha256=WYHL5DojY0hhYiV2mSEpEXsW6z9k2tmcnqp41UuksKE,603
+cave_cli/commands/list_cmd.py,sha256=fpeDAwhejC5ipwl7mxNQWbAr18YqF8ZjBXps9Ct8yjw,1236
+cave_cli/commands/list_versions.py,sha256=NpoqTJ7LMKA9T77gtl5SP1SjtLSkwr4S3RbO1Dln3q0,2649
+cave_cli/commands/prettify.py,sha256=eQb11E9jAfZT8E_anQ3bzGsoKAp-Gpn3llFTxJFFKOA,704
+cave_cli/commands/purge.py,sha256=EkSg3sMJDawJGtQXzWIlOgArkcQk19UhVsHjY_7RsCA,1915
+cave_cli/commands/reset.py,sha256=bVGBouEjLCsnc4wa2BN2HdCtTXDDd05sDNpekWKSwbM,1239
+cave_cli/commands/run.py,sha256=gaXqPXw6VQrLY7sivtNAIBdCSmG4BgamnIVFcNEldBo,5669
+cave_cli/commands/sync_cmd.py,sha256=dZAED2fOBFIgXxt6itw6gTZaf6F4ABHyQ5AjZ3aStt8,2163
+cave_cli/commands/test.py,sha256=SLbpFiYpKl3_7wzL_NfLMSl7LxJW-nqjoAUOgvEWmrk,978
+cave_cli/commands/uninstall.py,sha256=v34VoFo7tYphUYciloYGMgRLSNGJtkGKE1yYLE5RUno,971
+cave_cli/commands/update.py,sha256=o_HB4d3YmUjRGahvKSokqmQvMBdGWehNksX6-IRCbhM,991
+cave_cli/commands/upgrade.py,sha256=fLeEhWjuCeFFPXafb4vAG_9NN6IdVLGwRXJf25DELLQ,2199
+cave_cli/commands/version.py,sha256=eIvBERe1_MaN7DwDyeOIhnUD0rOfq4Z8W2Z5onqHQVE,1924
+cave_cli/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cave_cli/utils/cache.py,sha256=lutofWOa9cLSdDkVnSRm_PSzarxN_GosZZN2yunSt_g,6068
+cave_cli/utils/constants.py,sha256=IPgGvBj2BVyiXrFAWfIKPqI6Q_jhAhElqjAMmfiA4C8,1123
+cave_cli/utils/docker.py,sha256=Fj3fRgHOVqkXZP2gmsShmXJ1f4bGX-ypl1POww6EIs4,12553
+cave_cli/utils/env.py,sha256=nlKKLOKtetviMLfpqkdhd7I_CiMU601lh2mxW6DC5mM,7154
+cave_cli/utils/git.py,sha256=Dx8IwnLQ5yA_n_En13nP8IBycV1LcguB1xjJQyUpOdo,4672
+cave_cli/utils/logger.py,sha256=qELmwrAMCJ8xxd6dV4hfgGczg6XLnHN_1mAcBb09zZA,1849
+cave_cli/utils/net.py,sha256=qpKKACgrgJLW_BdciFd7EVtBvcBRk8oCimLwk4JqGIg,1866
+cave_cli/utils/subprocess.py,sha256=s6a1VvAmfNo3uQnuckW9CbVlCwYkf5070AXdzygZa28,2877
+cave_cli/utils/sync.py,sha256=-1Fma2Y923zKjyI6g5FmuUHkEdRSc5Rk_K7mlbSHdtk,2348
+cave_cli/utils/validate.py,sha256=5B8vPls699IJhDckSmEJ68Ew6F4AeJ8rayRP2gL97MQ,5656
+cave_cli-3.5.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+cave_cli-3.5.0.dist-info/licenses/NOTICE.md,sha256=2qN436eW01DWcPaXriThoEXhGNqG8OHNrHWYsGd2t3Q,631
+cave_cli-3.5.0.dist-info/METADATA,sha256=KHtpHl-BxKhNnECgIicrugyfxH7MT_UrQyKeZ124JXc,4092
+cave_cli-3.5.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cave_cli-3.5.0.dist-info/entry_points.txt,sha256=rxKeJ_S2t0gTfCyPYSAEYlWF1H7D-kjUer8DQP3fldY,43
+cave_cli-3.5.0.dist-info/top_level.txt,sha256=CDnV_I6P0bNNl97Ao7S-2Dqe0K0TFs_1TcPZiQkEXzw,9
+cave_cli-3.5.0.dist-info/RECORD,,

cave_cli-3.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cave_cli-3.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cave = cave_cli.cli:main