flashflow 0.1.0__tar.gz

flashflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Alberto Rosquete Ares
+
+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.

flashflow-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: flashflow
+Version: 0.1.0
+Summary: "flashflow" is a set of programs written in python to make easier everyday workflow
+Author-email: Pedro Alberto Rosquete Ares <rosquetearespedro06@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Pedro Alberto Rosquete Ares
+        
+        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.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# fastflow
+
+A small collection of Python commands for everyday development tasks.
+
+## Install for development
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+## Create a project scaffold
+
+Run this from the directory where you want the initial project files:
+
+```powershell
+fastflow project "My Project"
+```
+
+The command creates a virtual environment, `.gitignore`, `README.md`, `LICENSE`,
+and a valid `pyproject.toml` in the current directory. It refuses to overwrite
+any of those files if they already exist. Choose an actual license before
+distributing a generated project.
+
+## Release a Python project
+
+Run the command from the project root after choosing a new `X.Y.Z` version:
+
+```powershell
+fastflow release 1.2.3
+```
+
+The release command requires valid static `[project].version` metadata and a
+clean Git working tree. It updates the version, builds distributions from an
+isolated copy of the project, commits the version change locally, and uploads
+only those fresh artifacts to PyPI. After a successful upload, it asks whether
+to push the commit and whether to create and push a version tag.
+
+If the build fails, the previous version is restored. If the PyPI upload fails,
+the command attempts to remove its own release commit and restore the preceding
+commit, but reports that PyPI may have accepted the upload before the failure
+was returned. Verify the package on PyPI before retrying in that situation.

flashflow-0.1.0/README.md

@@ -0,0 +1,41 @@
+# fastflow
+
+A small collection of Python commands for everyday development tasks.
+
+## Install for development
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+## Create a project scaffold
+
+Run this from the directory where you want the initial project files:
+
+```powershell
+fastflow project "My Project"
+```
+
+The command creates a virtual environment, `.gitignore`, `README.md`, `LICENSE`,
+and a valid `pyproject.toml` in the current directory. It refuses to overwrite
+any of those files if they already exist. Choose an actual license before
+distributing a generated project.
+
+## Release a Python project
+
+Run the command from the project root after choosing a new `X.Y.Z` version:
+
+```powershell
+fastflow release 1.2.3
+```
+
+The release command requires valid static `[project].version` metadata and a
+clean Git working tree. It updates the version, builds distributions from an
+isolated copy of the project, commits the version change locally, and uploads
+only those fresh artifacts to PyPI. After a successful upload, it asks whether
+to push the commit and whether to create and push a version tag.
+
+If the build fails, the previous version is restored. If the PyPI upload fails,
+the command attempts to remove its own release commit and restore the preceding
+commit, but reports that PyPI may have accepted the upload before the failure
+was returned. Verify the package on PyPI before retrying in that situation.

flashflow-0.1.0/flashflow/__main__.py

@@ -0,0 +1,9 @@
+from .parser import Parser
+
+
+def main() -> None:
+    parser = Parser()
+    parser.start_parsing()
+
+if __name__ == "__main__":
+    main()

flashflow-0.1.0/flashflow/commands/project.py

@@ -0,0 +1,173 @@
+"""Create a safe, usable initial structure for a Python project."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import sys
+from argparse import Namespace
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..process import CommandExecutionError, ProcessRunner
+
+
+@dataclass(frozen=True)
+class Configuration:
+    """Select which project files and environment should be created."""
+
+    create_venv: bool = True
+    create_gitignore: bool = True
+    create_pyproject_toml: bool = True
+    create_readme: bool = True
+    create_license: bool = True
+
+
+class ProjectError(RuntimeError):
+    """An expected failure while creating a project scaffold."""
+
+
+class ProjectManager:
+    """Create project files without overwriting existing user data."""
+
+    def __init__(
+        self,
+        project_name: str,
+        config: Configuration | None = None,
+        project_dir: Path | str | None = None,
+        runner: ProcessRunner | None = None,
+    ) -> None:
+        self.name = project_name.strip()
+        if not self.name or re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._ -]*", self.name) is None:
+            raise ProjectError(
+                "Project name must start with a letter or digit and contain only "
+                "letters, digits, spaces, '.', '_' or '-'."
+            )
+
+        self.distribution_name = re.sub(r"[-_. ]+", "-", self.name).strip("-")
+        if not self.distribution_name:
+            raise ProjectError("Project name must contain at least one letter or digit.")
+
+        self.config = config or Configuration()
+        self.project_dir = Path.cwd() if project_dir is None else Path(project_dir).resolve()
+        self.runner = runner or ProcessRunner()
+        self._created_paths: list[Path] = []
+
+    def _file_contents(self) -> dict[str, str]:
+        files: dict[str, str] = {}
+
+        if self.config.create_gitignore:
+            files[".gitignore"] = (
+                "__pycache__/\n"
+                "*.py[cod]\n"
+                ".venv/\n"
+                ".vscode/\n"
+                ".cache/\n"
+                "build/\n"
+                "dist/\n"
+                "*.egg-info/\n"
+            )
+        if self.config.create_readme:
+            files["README.md"] = f"# {self.name}\n\nA short description of this project.\n"
+        if self.config.create_license:
+            files["LICENSE"] = "Choose and add a license before distributing this project.\n"
+        if self.config.create_pyproject_toml:
+            files["pyproject.toml"] = self._pyproject_contents()
+
+        return files
+
+    def _pyproject_contents(self) -> str:
+        lines = [
+            "[build-system]",
+            'requires = ["setuptools>=68"]',
+            'build-backend = "setuptools.build_meta"',
+            "",
+            "[project]",
+            f"name = {json.dumps(self.distribution_name)}",
+            'version = "0.1.0"',
+            f"description = {json.dumps('A Python project named ' + self.name + '.')}",
+            'requires-python = ">=3.9"',
+            "dependencies = []",
+        ]
+        if self.config.create_readme:
+            lines.append('readme = "README.md"')
+        lines.append("")
+        return "\n".join(lines)
+
+    def _preflight(self, files: dict[str, str]) -> None:
+        if not self.project_dir.is_dir():
+            raise ProjectError(f"Project directory does not exist: {self.project_dir}")
+
+        requested_paths = [self.project_dir / filename for filename in files]
+        if self.config.create_venv:
+            requested_paths.append(self.project_dir / ".venv")
+
+        conflicts = [
+            path.name for path in requested_paths if path.exists() or path.is_symlink()
+        ]
+        if conflicts:
+            joined = ", ".join(conflicts)
+            raise ProjectError(
+                f"Refusing to overwrite existing project content in {self.project_dir}: "
+                f"{joined}"
+            )
+
+    def create(self) -> list[Path]:
+        """Create the selected scaffold, rolling back only files created by this run."""
+        files = self._file_contents()
+        self._preflight(files)
+        self._created_paths = []
+
+        try:
+            for filename, content in files.items():
+                path = self.project_dir / filename
+                with path.open("x", encoding="utf-8", newline="\n") as project_file:
+                    self._created_paths.append(path)
+                    project_file.write(content)
+
+            if self.config.create_venv:
+                self._create_venv()
+        except (OSError, CommandExecutionError, ProjectError) as exc:
+            rollback_errors = self._rollback()
+            message = f"Project creation failed: {exc}"
+            if rollback_errors:
+                message += "\nCleanup was incomplete:\n" + "\n".join(rollback_errors)
+            raise ProjectError(message) from exc
+
+        return list(self._created_paths)
+
+    def _create_venv(self) -> None:
+        venv_path = self.project_dir / ".venv"
+        venv_path.mkdir()
+        self._created_paths.append(venv_path)
+        prompt = f"{self.distribution_name}-dev-venv"
+        self.runner.run(
+            [sys.executable, "-m", "venv", str(venv_path), "--prompt", prompt],
+            cwd=self.project_dir,
+        )
+
+    def _rollback(self) -> list[str]:
+        rollback_errors: list[str] = []
+        for path in reversed(self._created_paths):
+            try:
+                if path.is_dir() and not path.is_symlink():
+                    shutil.rmtree(path)
+                else:
+                    path.unlink(missing_ok=True)
+            except OSError as exc:
+                rollback_errors.append(f"{path}: {exc}")
+        self._created_paths.clear()
+        return rollback_errors
+
+
+def main(args: Namespace) -> None:
+    """Entry point for the project command."""
+    try:
+        created = ProjectManager(args.name).create()
+    except ProjectError as exc:
+        print(f"Project creation failed: {exc}")
+        raise SystemExit(1) from exc
+
+    for path in created:
+        print(f"Created {path.name}.")

flashflow-0.1.0/flashflow/commands/release.py

@@ -0,0 +1,360 @@
+"""Build and publish a new release of the current Python project."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from argparse import Namespace
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Callable
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.9 and 3.10
+    import tomli as tomllib  # type: ignore
+
+from ..confirm import confirm
+from ..process import CommandExecutionError, ProcessRunner
+
+_VERSION_RE = re.compile(r"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\Z")
+_SECTION_RE = re.compile(r"^\s*\[([^\]]+)]\s*(?:#.*)?$")
+_VERSION_LINE_RE = re.compile(
+    r"""(?P<prefix>\s*version\s*=\s*)(?P<quote>["'])(?P<version>[^"']+)(?P=quote)"""
+    r"""(?P<suffix>\s*(?:\#.*)?)(?P<newline>\r?\n?)\Z"""
+)
+Confirmer = Callable[[str], bool]
+
+
+class ReleaseError(RuntimeError):
+    """An expected failure while preparing or publishing a release."""
+
+
+class ReleaseManager:
+    """Coordinate release validation, local build/commit, and optional publication."""
+
+    def __init__(
+        self,
+        version: str,
+        project_dir: Path | str | None = None,
+        runner: ProcessRunner | None = None,
+        confirmer: Confirmer = confirm,
+    ) -> None:
+        self.version = version.strip()
+        self.project_dir = Path.cwd() if project_dir is None else Path(project_dir).resolve()
+        self.pyproject_path = self.project_dir / "pyproject.toml"
+        self._runner = runner or ProcessRunner()
+        self._confirm = confirmer
+
+    @staticmethod
+    def validate_version(version: str) -> tuple[int, int, int]:
+        """Validate and return a strict numeric X.Y.Z version."""
+        match = _VERSION_RE.fullmatch(version)
+        if match is None:
+            raise ReleaseError("Version must follow semantic versioning: X.Y.Z.")
+        return tuple(map(int, match.groups())) # type: ignore
+
+    @classmethod
+    def is_version_increase(cls, new_version: str, current_version: str) -> bool:
+        """Return whether a valid version is greater than the current version."""
+        return cls.validate_version(new_version) > cls.validate_version(current_version)
+
+    def read_current_version(self) -> str:
+        """Read the static project version from valid TOML project metadata."""
+        if not self.pyproject_path.is_file():
+            raise ReleaseError(f"{self.pyproject_path} not found.")
+
+        content = self._read_pyproject_content()
+        try:
+            metadata = tomllib.loads(content)
+        except tomllib.TOMLDecodeError as exc:
+            raise ReleaseError(f"Invalid TOML in {self.pyproject_path}: {exc}") from exc
+
+        project = metadata.get("project")
+        if not isinstance(project, dict) or not isinstance(project.get("version"), str):
+            raise ReleaseError(f"A static [project].version is required in {self.pyproject_path}.")
+
+        version = project["version"]
+        self.validate_version(version)
+        return version
+
+    def update_version(self, version: str) -> None:
+        """Atomically replace only [project].version, preserving the rest of the file."""
+        self.validate_version(version)
+        content = self._read_pyproject_content()
+        lines = content.splitlines(keepends=True)
+        project_start = None
+        project_end = len(lines)
+
+        for index, line in enumerate(lines):
+            section = _SECTION_RE.fullmatch(line.rstrip("\r\n"))
+            if section is None:
+                continue
+            if section.group(1) == "project":
+                project_start = index + 1
+            elif project_start is not None:
+                project_end = index
+                break
+
+        if project_start is None:
+            raise ReleaseError(f"[project].version not found in {self.pyproject_path}.")
+
+        for index in range(project_start, project_end):
+            match = _VERSION_LINE_RE.fullmatch(lines[index])
+            if match is not None:
+                lines[index] = (
+                    f"{match.group('prefix')}{match.group('quote')}{version}"
+                    f"{match.group('quote')}{match.group('suffix')}{match.group('newline')}"
+                )
+                self._write_atomically("".join(lines))
+                return
+
+        raise ReleaseError(f"[project].version must be a static string in {self.pyproject_path}.")
+
+    def _read_pyproject_content(self) -> str:
+        try:
+            return self.pyproject_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ReleaseError(f"Could not read {self.pyproject_path}: {exc}") from exc
+
+    def _write_atomically(self, content: str) -> None:
+        temporary_path: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                newline="",
+                dir=self.project_dir,
+                prefix=".pyproject-",
+                suffix=".tmp",
+                delete=False,
+            ) as temporary_file:
+                temporary_path = Path(temporary_file.name)
+                temporary_file.write(content)
+                temporary_file.flush()
+                os.fsync(temporary_file.fileno())
+            os.chmod(temporary_path, self.pyproject_path.stat().st_mode)
+            os.replace(temporary_path, self.pyproject_path)
+        except OSError as exc:
+            if temporary_path is not None:
+                try:
+                    temporary_path.unlink(missing_ok=True)
+                except OSError as cleanup_error:
+                    raise ReleaseError(
+                        f"Could not update {self.pyproject_path}; failed to remove "
+                        f"{temporary_path}: {cleanup_error}"
+                    ) from cleanup_error
+            raise ReleaseError(f"Could not update {self.pyproject_path}: {exc}") from exc
+
+    def _run(
+        self, command: Sequence[str], cwd: Path | None = None
+    ) -> subprocess.CompletedProcess[str]:
+        try:
+            return self._runner.run(command, cwd=cwd or self.project_dir)
+        except CommandExecutionError as exc:
+            raise ReleaseError(str(exc)) from exc
+
+    def check_git_state(self) -> None:
+        """Require a Git checkout with a clean working tree."""
+        branch = self._run(["git", "branch", "--show-current"]).stdout.strip()
+        if not branch:
+            raise ReleaseError("Cannot release from a detached HEAD.")
+        if branch != "main" and not self._confirm(
+            f"You are on branch '{branch}', not 'main'. Continue anyway?"
+        ):
+            raise ReleaseError("Release cancelled.")
+
+        status = self._run(["git", "status", "--porcelain"]).stdout.strip()
+        if status:
+            raise ReleaseError(
+                f"Working tree is not clean; commit or stash changes first:\n{status}"
+            )
+
+    def build(self, output_dir: Path, source_dir: Path) -> list[Path]:
+        """Build a copied source tree so backends leave no generated files in the project."""
+        output_dir.mkdir(parents=True, exist_ok=True)
+        self._run(
+            [
+                sys.executable,
+                "-m",
+                "build",
+                "--outdir",
+                str(output_dir),
+            ],
+            cwd=source_dir,
+        )
+        artifacts = sorted(path for path in output_dir.iterdir() if path.is_file())
+        if not artifacts:
+            raise ReleaseError("Build completed but produced no distribution files.")
+        return artifacts
+
+    def commit(self) -> tuple[str, str]:
+        """Commit the version change locally and return its parent and new commit IDs."""
+        parent = self._run(["git", "rev-parse", "HEAD"]).stdout.strip()
+        # -- prevents ambiguity and ensures Git treats pyproject.toml as a path,
+        # not as a git option.
+        self._run(["git", "add", "--", "pyproject.toml"])
+        self._run(["git", "commit", "-m", f"Release v{self.version}"])
+        release_commit = self._run(["git", "rev-parse", "HEAD"]).stdout.strip()
+        if not parent or not release_commit or parent == release_commit:
+            raise ReleaseError("Could not verify the local release commit.")
+        return parent, release_commit
+
+    def upload(self, artifacts: Sequence[Path]) -> None:
+        """Upload only artifacts produced by this release build."""
+        self._run(
+            [
+                sys.executable,
+                "-m",
+                "twine",
+                "upload",
+                "--verbose",
+                *(str(path) for path in artifacts),
+            ]
+        )
+
+    def publish_to_git(self) -> None:
+        """Offer optional branch push and version-tag publication."""
+        if self._confirm("Push the release commit to origin?"):
+            try:
+                self._run(["git", "push"])
+            except ReleaseError as exc:
+                raise ReleaseError(
+                    f"PyPI upload succeeded, but pushing the release commit failed: {exc}"
+                ) from exc
+            print("Pushed release commit.")
+
+        tag = f"v{self.version}"
+        if self._confirm(f"Create and push git tag {tag}?"):
+            try:
+                self._run(["git", "tag", tag])
+                self._run(["git", "push", "origin", tag])
+            except ReleaseError as exc:
+                raise ReleaseError(
+                    f"PyPI upload succeeded, but publishing Git tag {tag} failed: {exc}"
+                ) from exc
+            print(f"Pushed tag {tag}.")
+
+    def release(self) -> None:
+        """Validate, build, commit, upload, and optionally publish to Git."""
+        self.validate_version(self.version)
+        current_version = self.read_current_version()
+        if not self.is_version_increase(self.version, current_version):
+            raise ReleaseError(
+                f"Invalid version bump from {current_version} to {self.version}."
+            )
+        self.check_git_state()
+
+        original_content = self._read_pyproject_content()
+        self.update_version(self.version)
+        print(f"Updated version to {self.version} in pyproject.toml.")
+
+        with tempfile.TemporaryDirectory(prefix="fastflow-release-") as temporary_dir:
+            build_root = Path(temporary_dir)
+            output_dir = build_root / "dist"
+            source_dir = build_root / "source"
+            try:
+                print("Building package...")
+                shutil.copytree(
+                    self.project_dir,
+                    source_dir,
+                    ignore=self._ignore_build_files,
+                )
+                artifacts = self.build(output_dir, source_dir)
+            except (OSError, ReleaseError) as exc:
+                self._write_atomically(original_content)
+                raise ReleaseError(
+                    f"Build failed; restored the original project version. {exc}"
+                ) from exc
+            print("Build completed.")
+
+            try:
+                parent_commit, release_commit = self.commit()
+            except ReleaseError as exc:
+                self._restore_after_commit_failure(original_content)
+                raise ReleaseError(
+                    f"Local release commit failed; restored the original project version. {exc}"
+                ) from exc
+            print(f"Committed release v{self.version}.")
+
+            print("Uploading to PyPI...")
+            try:
+                self.upload(artifacts)
+            except ReleaseError as exc:
+                try:
+                    self._rollback_release_commit(parent_commit, release_commit)
+                except ReleaseError as rollback_error:
+                    raise ReleaseError(
+                        f"PyPI upload failed: {exc}\n"
+                        f"Could not safely roll back the local release commit: {rollback_error}"
+                    ) from exc
+                raise ReleaseError(
+                    "PyPI upload failed; the local release commit was removed and "
+                    f"the previous version restored. PyPI may have accepted the upload "
+                    f"before the failure was reported. {exc}"
+                ) from exc
+            print("Upload completed.")
+
+        self.publish_to_git()
+        print(f"Release v{self.version} successful.")
+
+    @staticmethod
+    def _ignore_build_files(directory: str, names: list[str]) -> set[str]:
+        del directory
+        ignored = {
+            ".git",
+            ".venv",
+            ".cache",
+            ".pytest_cache",
+            ".ruff_cache",
+            "__pycache__",
+            "build",
+            "dist",
+        }
+        return {
+            name
+            for name in names
+            if name in ignored or name.endswith(".egg-info")
+        }
+
+    def _rollback_release_commit(self, parent_commit: str, release_commit: str) -> None:
+        head = self._run(["git", "rev-parse", "HEAD"]).stdout.strip()
+        if head != release_commit:
+            raise ReleaseError(
+                "HEAD changed after the release commit; refusing to reset unrelated history."
+            )
+
+        status = self._run(["git", "status", "--porcelain"]).stdout.strip()
+        if status:
+            raise ReleaseError(
+                "The working tree changed after the release commit; refusing to discard "
+                f"those changes:\n{status}"
+            )
+
+        self._run(["git", "reset", "--hard", parent_commit])
+
+    def _restore_after_commit_failure(self, original_content: str) -> None:
+        unstage_error = None
+        try:
+            self._run(["git", "restore", "--staged", "--", "pyproject.toml"])
+        except ReleaseError as exc:
+            unstage_error = exc
+        self._write_atomically(original_content)
+        if unstage_error is not None:
+            raise ReleaseError(
+                "Restored the project version but could not unstage pyproject.toml: "
+                f"{unstage_error}"
+            ) from unstage_error
+
+
+def main(args: Namespace) -> None:
+    """Entry point for the release command."""
+    try:
+        ReleaseManager(args.version).release()
+    except ReleaseError as exc:
+        print(f"Release failed: {exc}")
+        raise SystemExit(1) from exc

flashflow-0.1.0/flashflow/confirm.py

@@ -0,0 +1,4 @@
+def confirm(prompt: str) -> bool:
+    """Ask for yes/no confirmation."""
+    response = input(f"{prompt} (y/n): ").strip().lower()
+    return response in ("y", "yes")

flashflow-0.1.0/flashflow/parser.py

@@ -0,0 +1,72 @@
+"""
+Module to centralize all handling of arguments throug CLI
+"""
+
+
+from argparse import ArgumentParser, Namespace
+
+from .commands import project, release
+
+
+class Parser:
+    """A class to manage all the argument parser and command features."""
+
+    def __init__(self) -> None:
+        """Initialize the CLIApp attributes."""
+        self.main_parser = self.build_parser()
+
+    def build_parser(self) -> ArgumentParser:
+        """Create the main parser and sub-commands."""
+        parser = ArgumentParser(
+            prog="fastflow", 
+            description="\"fastflow\" is a set of programs written in python \
+                to make easier everyday workflow",
+            allow_abbrev=False, 
+            epilog="Thanks for using %(prog)s, all feedback is appreciated"
+        ) 
+        
+        sub_commands = parser.add_subparsers(title="Programs", help="Programs available")
+        
+        # PROJECT
+        new_project_parser = sub_commands.add_parser(
+            "project",
+            help = "Create the initial structure for a new project in the current directory"
+        )
+        
+        new_project_parser.add_argument(
+            "name", type=str, help="Name of the project to be created."
+        )
+        
+        new_project_parser.set_defaults(func=project.main)
+        
+        # RELEASE
+        release_parser = sub_commands.add_parser(
+            "release", 
+            help = "Release an especific version of a program/package to PyPi."
+        )
+        
+        release_parser.add_argument(
+            "version", type=str, help="Version of the program to be uploaded"
+        )
+        release_parser.set_defaults(func=release.main)
+        
+        return parser
+
+    def start_parsing(self) -> None:
+        """Parses the arguments passed."""
+        args: Namespace
+        try:
+            args = self.main_parser.parse_args()
+        except ValueError as exc:
+            self.main_parser.error(str(exc))
+
+        if not hasattr(args, "func"):
+            # in case user invokes the program without arguments like:
+            # >>> fastflow
+            self.main_parser.print_help()
+            return
+        
+        try:
+            return args.func(args)
+        except (KeyError, ValueError) as exc:
+            self.main_parser.error(str(exc))

flashflow-0.1.0/flashflow/process.py

@@ -0,0 +1,81 @@
+"""Shared, shell-free subprocess execution for fastflow commands."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+
+class CommandExecutionError(RuntimeError):
+    """A subprocess could not be started or exited unsuccessfully."""
+
+    def __init__(
+        self,
+        command: Sequence[str],
+        returncode: int | None,
+        stdout: str | None = None,
+        stderr: str | None = None,
+        cause: OSError | subprocess.CalledProcessError | None = None,
+    ) -> None:
+        self.command = tuple(command)
+        self.returncode = returncode
+        self.stdout = stdout or ""
+        self.stderr = stderr or ""
+
+        command_text = subprocess.list2cmdline(self.command)
+        if returncode is None:
+            message = f"Could not start command ({command_text}): {cause}"
+        else:
+            message = f"Command ({command_text}) exited with status {returncode}."
+            if self.stdout.strip():
+                message += f"\nstdout:\n{self.stdout.strip()}"
+            if self.stderr.strip():
+                message += f"\nstderr:\n{self.stderr.strip()}"
+        super().__init__(message)
+
+
+CommandExecutor = Callable[..., subprocess.CompletedProcess[str]]
+
+class ProcessRunner:
+    """Run argument-list commands and surface complete, actionable failures."""
+
+    def __init__(self, executor: CommandExecutor = subprocess.run) -> None:
+        self._executor = executor
+
+    def run(
+        self,
+        command: Sequence[str],
+        *,
+        cwd: Path | str | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        if not command or any(not isinstance(part, str) for part in command):
+            raise ValueError("Commands must be non-empty sequences of strings.")
+
+        try:
+            result = self._executor(
+                list(command),
+                cwd=cwd,
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            raise CommandExecutionError(
+                command,
+                exc.returncode,
+                stdout=exc.stdout,
+                stderr=exc.stderr,
+                cause=exc,
+            ) from exc
+        except OSError as exc:
+            raise CommandExecutionError(command, None, cause=exc) from exc
+
+        if result.returncode:
+            raise CommandExecutionError(
+                command,
+                result.returncode,
+                stdout=result.stdout,
+                stderr=result.stderr,
+            )
+        return result

flashflow-0.1.0/flashflow.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: flashflow
+Version: 0.1.0
+Summary: "flashflow" is a set of programs written in python to make easier everyday workflow
+Author-email: Pedro Alberto Rosquete Ares <rosquetearespedro06@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Pedro Alberto Rosquete Ares
+        
+        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.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# fastflow
+
+A small collection of Python commands for everyday development tasks.
+
+## Install for development
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+## Create a project scaffold
+
+Run this from the directory where you want the initial project files:
+
+```powershell
+fastflow project "My Project"
+```
+
+The command creates a virtual environment, `.gitignore`, `README.md`, `LICENSE`,
+and a valid `pyproject.toml` in the current directory. It refuses to overwrite
+any of those files if they already exist. Choose an actual license before
+distributing a generated project.
+
+## Release a Python project
+
+Run the command from the project root after choosing a new `X.Y.Z` version:
+
+```powershell
+fastflow release 1.2.3
+```
+
+The release command requires valid static `[project].version` metadata and a
+clean Git working tree. It updates the version, builds distributions from an
+isolated copy of the project, commits the version change locally, and uploads
+only those fresh artifacts to PyPI. After a successful upload, it asks whether
+to push the commit and whether to create and push a version tag.
+
+If the build fails, the previous version is restored. If the PyPI upload fails,
+the command attempts to remove its own release commit and restore the preceding
+commit, but reports that PyPI may have accepted the upload before the failure
+was returned. Verify the package on PyPI before retrying in that situation.

flashflow-0.1.0/flashflow.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+flashflow/__init__.py
+flashflow/__main__.py
+flashflow/confirm.py
+flashflow/parser.py
+flashflow/process.py
+flashflow.egg-info/PKG-INFO
+flashflow.egg-info/SOURCES.txt
+flashflow.egg-info/dependency_links.txt
+flashflow.egg-info/entry_points.txt
+flashflow.egg-info/requires.txt
+flashflow.egg-info/top_level.txt
+flashflow/commands/project.py
+flashflow/commands/release.py

flashflow-0.1.0/flashflow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flashflow-0.1.0/flashflow.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flashflow = flashflow.__main__:main

flashflow-0.1.0/flashflow.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[:python_version < "3.11"]
+tomli>=2
+
+[dev]
+pytest>=8.0
+ruff>=0.1.0

flashflow-0.1.0/flashflow.egg-info/top_level.txt

@@ -0,0 +1 @@
+flashflow

flashflow-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flashflow"
+version = "0.1.0"
+description = "\"flashflow\" is a set of programs written in python to make easier everyday workflow"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{name = "Pedro Alberto Rosquete Ares", email = "rosquetearespedro06@gmail.com"}]
+license = { file = "LICENSE" }
+dependencies = ["tomli>=2; python_version < '3.11'"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.1.0"]
+
+[project.urls]
+
+[project.scripts]
+flashflow = "flashflow.__main__:main"
+
+[tool.setuptools.packages.find]
+include = ["flashflow*"]
+
+# PYTEST
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra"
+cache_dir = "./.cache/pytest"
+
+# RUFF
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+output-format = "grouped" # (groups by file), default is 'full'
+show-fixes = true
+extend-exclude = ["tests/*"]
+cache-dir = "./.cache/ruff"
+
+[tool.ruff.lint]
+select = [
+    "E", # pycodestyle
+    "F", # Pyflakes
+    "I", # isort
+    "B", # flake8-bugbear
+    "UP", # pyupgrade
+    "SIM", # flake8-simplify
+    "C4", # flake8-comprehensions
+]
+ignore = [
+    'DTZ001', 'DTZ005', 'DTZ007', 'DTZ011', # datetime-timezone-checks
+    'E101' # indentation contains mixed spaces and tabs
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

flashflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+