kcm-workspace 0.1.0__py3-none-any.whl

kcm_workspace/__init__.py

@@ -0,0 +1,5 @@
+from .color import Color
+from .workspace import HOME, GitClone, Workspace
+
+__all__ = ["HOME", "Color", "GitClone", "Workspace"]
+__version__ = "0.1.0"

kcm_workspace/color.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+
+class Color:
+    ENDC = "\033[0m"
+
+    @staticmethod
+    def r(text: str | Path) -> str:
+        """Returns a *red* string"""
+        return f"\033[91m{text}{Color.ENDC}"
+
+    @staticmethod
+    def b(text: str | Path) -> str:
+        """Returns a *blue* string"""
+        return f"\033[94m{text}{Color.ENDC}"
+
+    @staticmethod
+    def g(text: str | Path) -> str:
+        """Returns a *green* string"""
+        return f"\033[92m{text}{Color.ENDC}"
+
+    @staticmethod
+    def c(text: str | Path) -> str:
+        """Returns a *cyan* string"""
+        return f"\033[96m{text}{Color.ENDC}"
+
+    @staticmethod
+    def m(text: str | Path) -> str:
+        """Returns a *magenta* string"""
+        return f"\033[95m{text}{Color.ENDC}"
+
+    @staticmethod
+    def y(text: str | Path) -> str:
+        """Returns a *yellow* string"""
+        return f"\033[93m{text}{Color.ENDC}"
+
+    @staticmethod
+    def s(text: str | Path) -> str:
+        """Returns a *strong* string"""
+        return f"\033[1m{text}{Color.ENDC}"
+
+    @staticmethod
+    def u(text: str | Path) -> str:
+        """Returns a *underlined* string"""
+        return f"\033[4m{text}{Color.ENDC}"

kcm_workspace/workspace.py

@@ -0,0 +1,425 @@
+import glob
+import inspect
+import os
+import re
+import subprocess  # nosec B404
+import sys
+import time
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .color import Color
+
+HOME = Path(os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~"))
+WINDOWS_HOSTS = Path(r"C:\Windows\System32\drivers\etc\hosts")
+POSIX_HOSTS = Path("/etc/hosts")
+
+NATIVES = {
+    "build": "Build or rebuild services.",
+    "convert": "Converts the compose file to platform's canonical format.",
+    "cp": "Copy files/folders between a service container and the local filesystem.",
+    "create": "Creates containers for a service.",
+    "down": "Stop and remove containers: networks.",
+    "events": "Receive real time events from containers.",
+    "exec": "Execute a command in a running container.",
+    "images": "List images used by the created containers.",
+    "kill": "Force stop service containers.",
+    "logs": "View output from containers.",
+    "ls": "List running compose projects.",
+    "pause": "Pause services.",
+    "port": "Print the public port for a port binding.",
+    "ps": "List containers.",
+    "pull": "Pull service images.",
+    "push": "Push service images.",
+    "restart": "Restart service containers.",
+    "rm": "Removes stopped service containers.",
+    "run": "Run a one-off command on a service.",
+    "start": "Start services.",
+    "stop": "Stop services.",
+    "top": "Display the running processes.",
+    "unpause": "Unpause services.,",
+    "up": "Create and start containers.",
+    "version": "Show the Docker Compose version information.",
+}
+
+
+@dataclass
+class GitClone:
+    """Repositório a ser clonado. ``folder`` relativo é resolvido a partir da pasta do projeto."""
+
+    folder: str | Path
+    url: str
+    branch: str = "main"
+
+
+class Workspace:
+    """Base dos scripts de workspace.
+
+    Cada projeto estende esta classe e informa no construtor o que é específico dele.
+    Um método vira comando quando a docstring termina com ``Aplica-se a: <escopos>``.
+    """
+
+    def __init__(
+        self,
+        script_file: str | Path,
+        git_clones: list[GitClone] | None = None,
+        mk_volumes: list[str] | None = None,
+        moodle_plugins: list[str] | None = None,
+        cli_dict: dict[str, str] | None = None,
+        shell_dict: dict[str, str] | None = None,
+        argv: list[str] | None = None,
+    ):
+        self.script = Path(script_file).resolve()
+        self.project_name = self.script.stem
+        self.workspace_dir = self.script.parent
+        self.project_dir = self.workspace_dir.parent
+        self.volumes_dir = Path(os.environ.get("VOLUMES_DIR", self.project_dir / "volumes"))
+        self.home = HOME
+
+        self.git_clones = [GitClone(self.project_dir / g.folder, g.url, g.branch) for g in (git_clones or [])]
+        self.mk_volumes = mk_volumes or []
+        self.moodle_plugins = moodle_plugins or []
+        self.cli_dict = cli_dict or {}
+        self.shell_dict = shell_dict or {}
+
+        self.argv = list(sys.argv if argv is None else argv)
+        self._command_name = self.argv[1] if len(self.argv) > 1 else "help"
+        self._scope_name = self.argv[2] if len(self.argv) >= 3 else "env"
+        self._service_name = self._scope_name if self._scope_name != "env" else ""
+
+        self._services: list[str] = []
+        self._repositories: set[str] = set()
+        self._commands: dict = {}
+        self._scopes: dict[str, list[str]] = {}
+        self._descriptions: dict[str, str] = {}
+
+    # ------------------------------------------------------------------ execução
+
+    def run(self) -> int:
+        """Lê .env e docker compose, carrega os comandos e executa o solicitado."""
+        try:
+            os.chdir(self.workspace_dir)
+            print(f"Trabalhando em {Color.c(self.workspace_dir)}")
+            self._read_envs()
+            self._read_compose()
+            self._load_commands()
+            if len(self.argv) == 1:
+                return self.help()
+            if self._command_name not in self._commands:
+                print(f"{Color.g('docker compose')} {Color.b(self._command_name)} {Color.m(' '.join(self.argv[2:]))}")
+                return self._execute("docker", "compose", *self.argv[1:])
+            return self._commands[self._command_name]() or 0
+        except KeyboardInterrupt:
+            print(f"\n{Color.r('Interrompido pelo usuário')}")
+            return 130
+
+    @classmethod
+    def main(cls) -> None:
+        """Ponto de entrada: ``if __name__ == "__main__": MeuProjeto.main()``."""
+        sys.exit(cls().run())
+
+    # ------------------------------------------------------------------ internos
+
+    def _read_envs(self) -> None:
+        env_file = self.workspace_dir / ".env"
+        if not env_file.exists():
+            return
+        try:
+            content = env_file.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            content = env_file.read_text()
+        for line in content.splitlines():
+            if line.startswith("#") or line.strip() == "" or "=" not in line:
+                continue
+            varname, varval = line.split("=", 1)
+            if varname == "COMPOSE_PROJECT_NAME" and varval != self.project_name:
+                raise ValueError(f"No arquivo .env está como {line}, mas devia ser {varname}={self.project_name}")
+            os.environ[varname] = varval
+
+    def _read_compose(self) -> None:
+        result = subprocess.run(  # nosec B603 B607
+            ["docker", "compose", "config"], capture_output=True, text=True, cwd=self.workspace_dir
+        )
+        self._services = []
+        repositories = [""]
+        for line in result.stdout.splitlines():
+            service = re.search(r"^  (\w*):$", line)
+            if service and service.group(1) != "default":
+                self._services.append(service.group(1))
+            image = re.search(r"^(    image: )(.*)$", line)
+            if image:
+                name = image.group(2)
+                repositories.append(name.split("/")[0] if name.count("/") > 1 else "")
+        self._repositories = set(repositories)
+
+    def _load_commands(self) -> None:
+        for name, func in inspect.getmembers(type(self), inspect.isfunction):
+            match = re.search(r"^(.*)(Aplica-se a: )(.*)$", func.__doc__ or "", re.MULTILINE)
+            if match is None:
+                continue
+            scopes = match.group(3)
+            scopes = scopes.replace("$services_names$", ",".join(self._services))
+            scopes = scopes.replace("$restore_dirs$", ",".join(self._prefixed_envs("RESTORE_DIR_").keys()))
+            scopes = scopes.replace("$download_files$", ",".join(self._prefixed_envs("DOWNLOAD_FILE").keys()))
+            self._commands[name] = getattr(self, name)
+            self._scopes[name] = scopes.split(",")
+            self._descriptions[name] = match.group(1) + match.group(2)
+
+    def _container_lines(self) -> list[str]:
+        result = subprocess.run(["docker", "container", "ps"], capture_output=True, text=True)  # nosec B603 B607
+        return result.stdout.splitlines()
+
+    def _service_is_running(self, service_name: str) -> bool:
+        pattern = f".*{self.project_name}-{service_name}-1.*"
+        return any(re.match(pattern, line) for line in self._container_lines())
+
+    def _service_is_healthy(self, service_name: str) -> bool:
+        pattern = f".*{self.project_name}-{service_name}-1.*"
+        return any(re.match(pattern, line) and "healthy" in line for line in self._container_lines())
+
+    def _execute(self, executable_file: str, *args: str) -> int:
+        command = " ".join([executable_file, *args])
+        print(Color.g("Executando: "), Color.b(command))
+        p = subprocess.Popen(  # nosec B602
+            command, stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stdout, shell=True, cwd=self.workspace_dir
+        )
+        return p.wait()
+
+    def _write_shell_file(self, filename: str) -> None:
+        shell_file = self.home / filename
+        if shell_file.exists() and str(self.workspace_dir) not in shell_file.read_text(encoding="utf-8"):
+            with shell_file.open("a", encoding="utf-8") as f:
+                f.write(f"\nPATH=$PATH:{self.workspace_dir}\n")
+            print("Lembre-se de executar o comando abaixo:")
+            print(Color.g(f"source ~/{filename}"), "\n")
+
+    @staticmethod
+    def _prefixed_envs(prefix: str) -> dict[str, str]:
+        return {k[len(prefix) :].lower(): v for k, v in os.environ.items() if k.startswith(prefix)}
+
+    @property
+    def _verb(self) -> str:
+        return "exec" if self._service_is_running(self._service_name) else "run --rm"
+
+    @property
+    def _default_django(self) -> str:
+        django_svc = os.environ.get("DEFAULT_DJANGO", "web")
+        return django_svc if django_svc in self._services else "web"
+
+    def _resolve_django_service_and_args(self) -> tuple[str, str, list[str]]:
+        if self._service_name in self._services:
+            service, args = self._service_name, self.argv[3:]
+        else:
+            service, args = self._default_django, self.argv[2:]
+        verb = "exec" if self._service_is_running(service) else "run --rm"
+        return service, verb, args
+
+    def _write_hosts(self) -> None:
+        hosts = self._prefixed_envs("HOSTS")
+        if "" not in hosts or ":" not in hosts[""]:
+            return
+        hosts_name, hosts_value = hosts[""].split(":", 1)
+        hosts_file = WINDOWS_HOSTS if sys.platform == "win32" else POSIX_HOSTS
+        try:
+            content = hosts_file.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            print(Color.y(f"Arquivo de hosts ({hosts_file}) não encontrado."))
+            return
+        if hosts_value in content:
+            return
+        print(f"Adicionando este {hosts_value} em {hosts_file}:")
+        nls = "#" * 70
+        new_hosts = f"\n{nls}\n## {hosts_name}\n{nls}\n{hosts_value}\n"
+        if sys.platform != "win32":
+            self._execute(f"echo '{new_hosts}' | sudo tee -a {hosts_file}")
+            return
+        try:
+            with hosts_file.open("a", encoding="utf-8") as f:
+                f.write(new_hosts)
+        except PermissionError:
+            print(
+                Color.r(
+                    f"Permissão negada ao escrever em {hosts_file}. Execute o terminal como Administrador "
+                    f"ou adicione manualmente a linha abaixo em {hosts_file}:\n{hosts_value}"
+                )
+            )
+
+    def _mk_volumes(self) -> None:
+        for mkvol in self.mk_volumes:
+            vol = self.volumes_dir / mkvol
+            print(vol)
+            vol.mkdir(parents=True, exist_ok=True)
+            if sys.platform != "win32":
+                self._execute(f"sudo chmod -R 777 {vol}")
+
+    # ------------------------------------------------------------------ comandos
+
+    def help(self) -> int:
+        """Imprime esta ajuda. Aplica-se a: env"""
+        print(f"""Uso:\n{Color.r(f'{self.project_name} [OPTIONS] COMMAND')}\n\nOptions:
+    {Color.m('--ansi')} {Color.y('string')}                Control when to print ANSI control characters ("never"|"always"|"auto") (default "auto")
+    {Color.m('--compatibility')}              Run compose in backward compatibility mode
+    {Color.m('--env-file')} {Color.y('string')}            Specify an alternate environment file.
+{Color.m('-f')}, {Color.m('--file')} {Color.y('stringArray')}           Compose configuration files
+    {Color.m('--profile')} {Color.y('stringArray')}        Specify a profile to enable
+    {Color.m('--project-directory')} {Color.y('string')}   Specify an alternate working directory (default: the path of the, first specified, Compose file)
+    {Color.m('-p')}, {Color.m('--project-name')} {Color.y('string')}    Project name\nComandos:""")  # noqa: E501
+        for m in list(NATIVES.keys()) + list(self._commands.keys()):
+            fixed = Color.m(f"{m:22}")
+            description = self._descriptions.get(m, NATIVES.get(m, " Sem descrição"))
+            scopes = Color.c(", ".join(self._scopes.get(m, [" Ver `docker compose`"])))
+            print(f"  {fixed} - {description}{scopes}")
+        print(f"Execute '{self.script.name} COMMAND help' para imprimir a ajuda.")
+        return 0
+
+    def relaunch(self) -> int:
+        """Para e depois inicia ambiente ou o serviço especificado, não faz lock do CLI. Aplica-se a: $services_names$,env"""  # noqa: E501
+        self._execute(f"docker compose down {self._service_name}")
+        return self._execute(f"docker compose up -d {self._service_name}")
+
+    def launch(self) -> int:
+        """Mostra o status ambiente ou o serviço especificado. Aplica-se a: $services_names$,env"""
+        self.relaunch()
+        return self._execute(f"docker compose logs -f {self._service_name}")
+
+    def exec(self) -> int:
+        """Executa um comando em um serviço que já esteja em execução. Aplica-se a: $services_names$,env"""
+        return self._execute(f"docker compose {self._verb} {self._service_name} ", *self.argv[3:])
+
+    def clone(self) -> int:
+        """Clona todos os repositórios. Aplica-se a: env"""
+        for g in self.git_clones:
+            folder = Path(g.folder)
+            folder.parent.mkdir(mode=0o770, parents=True, exist_ok=True)
+            if not folder.exists():
+                print(f"Clonando {Color.c(folder)} do repositório {Color.y(g.url)} na branch {Color.m(g.branch)}")
+                self._execute(f'git clone -b {g.branch} {g.url} "{folder}"')
+        return 0
+
+    def setup(self) -> int:
+        """Executa o setup do ambiente, ou seja, clona todos os repositórios e configura o PATH e o hosts. Aplica-se a: env"""  # noqa: E501
+        self._execute(f"docker compose down {self._service_name}")
+        self.clone()
+        self._write_hosts()
+        self._mk_volumes()
+        self._write_shell_file(".bashrc")
+        self._write_shell_file(".zshrc")
+        return 0
+
+    def deploy(self) -> int:
+        """Para tudo, constrói as imagens, iniciar os serviços background e acompanha o log. Aplica-se a: env"""
+        self.setup()
+        return self._execute("docker compose up -d")
+
+    def undeploy(self) -> int:
+        """Pára todo o ambiente e remove os volumes. Aplica-se a: $services_names$,env"""
+        return self._execute("docker compose down -v")
+
+    def git(self) -> int:
+        """Executa o comando git em todos os repositórios git. Aplica-se a: env"""
+        git_arguments = " ".join(self.argv[2:]) if len(self.argv) > 2 else "status"
+        print(f"Executando {Color.b('git ' + git_arguments)} em {Color.m(self.workspace_dir)}")
+        self._execute(f'git -C "{self.workspace_dir}" {git_arguments}')
+        for g in self.git_clones:
+            if Path(g.folder).exists():
+                print(f"Executando {Color.b('git ' + git_arguments)} em {Color.m(g.folder)}")
+                self._execute(f'git -C "{g.folder}" {git_arguments}')
+            else:
+                print(f"O projeto {g.folder} NÃO foi clonado ainda.")
+        return 0
+
+    def cli(self) -> int:
+        """Executa a CLI padrão do serviço, pode ser php -a, shell_plus, psql ou redis-cli. Bash por padrão. Usará exec se possível, caso contrário será run. Aplica-se a: $services_names$"""  # noqa: E501
+        cmd = self.cli_dict.get(self._service_name, "bash")
+        return self._execute(f"docker compose {self._verb} {self._service_name} {cmd} ", *self.argv[3:])
+
+    def shell(self) -> int:
+        """Executa o bash ou sh de um serviço, usará exec se já estiver em execução, run caso contrário. Aplica-se a: $services_names$"""  # noqa: E501
+        cmd = self.shell_dict.get(self._service_name, "bash")
+        return self._execute(f"docker compose {self._verb} {self._service_name} {cmd} ", *self.argv[3:])
+
+    def shell_root(self) -> int:
+        """Executa o bash ou sh de um serviço como root, usará exec se já estiver em execução, run caso contrário. Aplica-se a: $services_names$"""  # noqa: E501
+        cmd = self.shell_dict.get(self._service_name, "bash")
+        return self._execute(f"docker compose {self._verb} -u root {self._service_name} {cmd} ", *self.argv[3:])
+
+    def wait(self) -> int:
+        """Aguarda até o banco de dados estar disponível. Aplica-se a: db"""
+        while not self._service_is_healthy("db"):
+            print(Color.y("Aguardando o banco de dados estar disponível..."))
+            time.sleep(3)
+        print(Color.g("Banco de dados disponível!"))
+        return 0
+
+    def manage(self) -> int:
+        """Executa o manage.py do do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python3 manage.py ", *args)
+
+    def makemigrations(self) -> int:
+        """Criar as migrações pendentes do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python3 manage.py makemigrations", *args)
+
+    def migrate(self) -> int:
+        """Aplica as migrações pendentes do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python3 manage.py migrate", *args)
+
+    def show_urls(self) -> int:
+        """Mostra as URL do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python manage.py show_urls", *args)
+
+    def test(self) -> int:
+        """Executa os testes unitários do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        self._execute(f"docker compose {verb} {service} coverage run manage.py test", *args)
+        return self._execute(f"docker compose {verb} {service} coverage report", *args)
+
+    def lint(self) -> int:
+        """Formata o código do serviço com black. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} black --line-length 120 .", *args)
+
+    def compress_plugins(self) -> int:
+        """Comprime todos os plugins Moodle. Aplica-se a: env"""
+
+        def zip_with_prefix(folder_path: Path, zip_path: Path, prefix: str) -> None:
+            zip_path.parent.mkdir(parents=True, exist_ok=True)
+            with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+                for file_path in folder_path.rglob("*"):
+                    if not file_path.is_file() or {".git", ".idea"} & set(file_path.parts):
+                        continue
+                    zipf.write(file_path, Path(prefix) / file_path.relative_to(folder_path))
+
+        build_dir = self.workspace_dir / "build" / "plugins"
+        for plugin_fullname in self.moodle_plugins:
+            plugin_name = plugin_fullname.split("_", 1)[1]
+            plugin_dir = self.project_dir / plugin_fullname
+            for line in (plugin_dir / "version.php").read_text(encoding="utf-8").splitlines():
+                if not line.startswith("$plugin->version"):
+                    continue
+                plugin_version = line.split("=")[1].replace(";", "").split()[0]
+                plugin_package = build_dir / f"{plugin_fullname}-{plugin_version}.zip"
+                if plugin_package.exists():
+                    print(f"Plugin {Color.c(plugin_package)} {Color.r('JÁ existe')}.")
+                    continue
+                print(f"Plugin {Color.c(plugin_package)} {Color.g('NÃO existe')}.")
+                for old_zip in glob.glob(str(build_dir / f"{plugin_fullname}-*.zip")):
+                    try:
+                        os.remove(old_zip)
+                    except OSError:
+                        pass
+                zip_with_prefix(plugin_dir, plugin_package, plugin_name)
+        return 0
+
+    def publish(self) -> int:
+        """Comprime os plugins Moodle e constrói e publica a imagem do serviço ava. Aplica-se a: env"""
+        self.compress_plugins()
+        return self._execute("docker compose build --progress plain --push ava")
+
+    def code(self) -> int:
+        """Abre o workspace no VS Code. Aplica-se a: env"""
+        return self._execute(f'code "{self.workspace_dir / f"{self.project_name}.code-workspace"}"')

kcm_workspace-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: kcm-workspace
+Version: 0.1.0
+Summary: Base class for docker compose workspace scripts (clone, setup, launch, shell, manage and more)
+Author-email: Kelson da Costa Medeiros <kelsoncm@gmail.com>
+License: # License
+        
+        ## The MIT License (MIT)
+        
+        Copyright (c) 2026 python-by-kelsoncm
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/python-by-kelsoncm/python-kcm-workspace
+Project-URL: Bug Tracker, https://github.com/python-by-kelsoncm/python-kcm-workspace/issues
+Project-URL: Download, https://github.com/python-by-kelsoncm/python-kcm-workspace/releases/
+Keywords: docker,compose,workspace,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+License-File: AUTHORS.md
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.6.0; extra == "dev"
+Requires-Dist: black>=26.3.1; extra == "dev"
+Requires-Dist: ruff>=0.15.11; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Dynamic: license-file
+
+# kcm-workspace
+
+Classe base para os scripts de workspace baseados em `docker compose`
+(`clone`, `setup`, `launch`, `shell`, `manage`, `git` e outros).
+
+Cada projeto tem, em `<projeto>/workspace/<projeto>`, um script que estende
+`Workspace` e informa no construtor o que é específico dele.
+
+## Uso
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["kcm-workspace>=0.1.0"]
+# ///
+from kcm_workspace import GitClone, Workspace
+
+GITBASE = "git@github.com:minha-org"
+
+
+class Projeto(Workspace):
+    def __init__(self):
+        super().__init__(
+            __file__,
+            git_clones=[GitClone("app", f"{GITBASE}/app.git")],
+            mk_volumes=["db"],
+            cli_dict={"db": "psql"},
+            shell_dict={"db": "sh"},
+        )
+
+    def collectstatic(self) -> int:
+        """Coleta os estáticos. Aplica-se a: $services_names$"""
+        return self._execute("docker compose exec web python manage.py collectstatic")
+
+
+if __name__ == "__main__":
+    Projeto.main()
+```
+
+- `GitClone.folder` relativo é resolvido a partir da pasta do projeto (pai de `workspace`).
+- Um método vira comando quando a docstring termina com `Aplica-se a: <escopos>`.
+- Comandos desconhecidos são repassados para `docker compose`.
+- No Windows, use um wrapper `<projeto>.ps1`:
+
+```powershell
+$nomeSemExtensao = (Get-Item $PSCommandPath).BaseName
+uv run --script "$PSScriptRoot\$nomeSemExtensao" @args
+```
+
+## Atributos disponíveis
+
+`project_name`, `project_dir`, `workspace_dir`, `volumes_dir`, `home`, `argv`,
+`git_clones`, `mk_volumes`, `moodle_plugins`, `cli_dict`, `shell_dict`.
+
+## Métodos auxiliares
+
+`_execute(cmd, *args)`, `_service_is_running(svc)`, `_service_is_healthy(svc)`,
+`_prefixed_envs(prefix)`, `_resolve_django_service_and_args()`, `_verb`.
+
+## Desenvolvimento
+
+```bash
+uv pip install -e ".[dev]"
+pytest --cov=kcm_workspace
+```

kcm_workspace-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+kcm_workspace/__init__.py,sha256=ZY4WQywsOg6s0ZZXvSpzvdfToqoD2uKZnEchtl4sTMo,150
+kcm_workspace/color.py,sha256=WdopDKsIe_6HZBaRuFXzzBT8D1y1CQrMgrO1TETNgDs,1176
+kcm_workspace/workspace.py,sha256=8hwIY1auhfOlJhXKSD3xM6xK7KQhcky4oSUJCKjd2hs,20460
+kcm_workspace-0.1.0.dist-info/licenses/AUTHORS.md,sha256=qk2yCTi5iFKzq5whkvvZ-Wq-Mj47xcoOJGJkbu_RnI0,84
+kcm_workspace-0.1.0.dist-info/licenses/LICENSE.md,sha256=mYRSY4lBNy3XDQwvexDjx4MsqTkyIosr8nZF4aqQRIE,1099
+kcm_workspace-0.1.0.dist-info/METADATA,sha256=ICt9N3jbWiv5qPKyahM4kwWj4FSRZmrbTyXcSi3QVf8,4631
+kcm_workspace-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+kcm_workspace-0.1.0.dist-info/top_level.txt,sha256=UNEdZyrbKwAK2Bv8lJ8aRMNYREtGgoEduZxKdRxfrqw,14
+kcm_workspace-0.1.0.dist-info/RECORD,,

kcm_workspace-0.1.0.dist-info/WHEEL

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

kcm_workspace-0.1.0.dist-info/licenses/AUTHORS.md

@@ -0,0 +1,3 @@
+# Authors
+
+- Kelson da Costa Medeiros <kelsoncm@gmail.com>, Tech Leader & Developer

kcm_workspace-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,23 @@
+# License
+
+## The MIT License (MIT)
+
+Copyright (c) 2026 python-by-kelsoncm
+
+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.

kcm_workspace-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kcm_workspace