repopy 0.1.0__tar.gz → 0.2.0__tar.gz

repopy-0.2.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: repopy
+Version: 0.2.0
+Summary: A modular CLI workspace initializer and cloning automation tool.
+Author-email: Janitha Manatunga <janithamanatunga@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/manatunga/repopy
+Project-URL: Repository, https://github.com/manatunga/repopy
+Project-URL: Bug Tracker, https://github.com/manatunga/repopy/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# repopy
+
+A modular, cross-platform Python CLI workspace manager and developer tooling suite designed to automate reproducible local scaffolding, virtual environment creation, and remote repository synchronization.
+
+![PyPI - Version](https://img.shields.io/pypi/v/repopy?color=orange)&nbsp;&nbsp;&nbsp;
+[![CI](https://github.com/manatunga/repopy/actions/workflows/tests.yml/badge.svg)](https://github.com/manatunga/repopy/actions/workflows/tests.yml)&nbsp;&nbsp;&nbsp;
+[![Python Versions](https://img.shields.io/pypi/pyversions/repopy.svg)](https://pypi.org)&nbsp;&nbsp;&nbsp;
+[![License: MIT](https://img.shields.io/pypi/l/repopy.svg)](https://opensource.org/license/mit)
+
+---
+
+## 🌟 Key Features
+
+- **Lifecycle Project Scaffolding (`repopy init`)**: Replaces manual setup by provisioning clean directory structures, virtual environments, automated `.gitignore` presets, and standardized metadata configurations (`pyproject.toml` or `requirements.txt`).
+
+- **Remote Cloning (`repopy clone`)**: Clones remote Git repositories into structured local footprints and auto-provisions dedicated virtual environments and dependencies.
+
+- **Upstream Linking (`repopy link`)**: Instantly connects an unlinked local workspace to a remote Git upstream, staging files, executing initial commits, and pushing to the default branch in one step.
+
+- **Architectural Themes**: Supports presets (`minimal`, `web_api`, `cli_package`, `data_science`) tailored to the specific packaging needs of the application.
+
+- **Transactional Cleanups**: Employs defensive rollback mechanisms (`shutil.rmtree`) to purge incomplete workspaces if initialization fails midway.
+
+- **Automated Test Suite & CI**: Fully covered by local `pytest` test suites and verified via continuous integration on GitHub Actions.
+
+---
+
+## 🛠️ Architecture & Separation of Concerns
+
+`repopy` is organized into single-responsibility layers:
+- **Presentation & Routing (`cli.py`, `prompts.py`, `__main__.py`)**: Evaluates native terminal arguments via `argparse`, orchestrates interactive prompt flows, and handles OS interrupts gracefully.
+
+- **Supervision (`orchestrators.py`)**: Broker layer executing lifecycle validation checks, branch sequencing, and command handoffs.
+
+- **Low-Level Engines (`file_system.py`, `git_engine.py`)**: Decoupled engines handling transactional directory allocations, venv isolation, and direct subprocess execution.
+
+- **Validation & Translation (`validators.py`, `dependencies.py`, `os_detector.py`)**: Sanitizes paths, ensures semantic regex compliance, verifies system binaries (such as `git`), and resolves cross-platform paths.
+
+---
+
+## 📥 Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install repopy
+```
+Alternatively, you can install the latest development version directly from the source:
+
+```bash
+git clone https://github.com/manatunga/repopy.git
+cd repopy
+pip install -e .
+```
+
+---
+
+## 🚀 Usage Guide
+
+### 1. Initialize a Project (`repopy init`)
+Generate a new workspace interactively or via CLI flags:
+
+```bash
+# Interactive setup
+repopy init my-app
+
+# Non-interactive generation with a specific theme
+repopy init my-api -t web_api -s
+
+# Initialize and immediately connect to a remote repository
+repopy init my-cli -t cli_package --link <git-url>
+```
+
+#### Available Themes:
+- `minimal`: Bare directory setup with `requirements.txt`.
+- `web_api`: Layered service layout prepared for modern frameworks.
+- `cli_package`: Modular structure configured with PEP 621 compliant `pyproject.toml`.
+- `data_science`: Notebooks, data folders, and pipeline layouts.
+<br>
+<br>
+
+### 2. Clone a Remote Project (`repopy clone`)
+Fetch a remote repository and immediately auto-provision an isolated `.venv`:
+
+```bash
+repopy clone <git-url> -n [custom-project-name]
+```
+
+<br>
+
+### 3. Link an Existing Workspace (`repopy link`)
+Run inside an existing workspace to push tracking history to an upstream origin:
+
+```bash
+repopy link <git-url> -m ["custom-initial-commit-message"]
+```
+
+---
+
+## 🧪 Testing & Continuous Integration
+
+Run the test suite using `pytest`:
+
+```bash
+pytest -v
+```
+
+All contributions and pull requests are validated through our GitHub Actions workflow matrix (`.github/workflows/tests.yml`), running integration and validation tests across supported Python versions.
+
+---
+
+## 🗂️ Project Structure
+
+```
+repopy/
+├── .github/
+│   └── workflows/
+│       └── tests.yml            # CI test runner pipeline
+├── src/
+│   └── repopy/
+│       ├── __init__.py          # Package initialization
+│       ├── __main__.py          # Application execution entry
+│       ├── cli.py               # CLI subparser configuration
+│       ├── dependencies.py      # Binary prerequisite verification
+│       ├── file_system.py       # Atomic workspace & venv operations
+│       ├── git_engine.py        # Subprocess Git execution engine
+│       ├── orchestrators.py     # High-level pipeline management
+│       ├── os_detector.py       # Cross-platform environment resolver
+│       ├── prompts.py           # Dynamic terminal questionnaires
+│       ├── templates.py         # Static asset definitions & manifests
+│       └── validators.py        # Input sanitation & regex filters
+├── tests/
+│   ├── test_prompts.py          # Input loop & default manifest tests
+│   └── test_validators.py       # Path and schema validation tests
+├── pyproject.toml               # PEP 621 packaging configuration
+├── LICENSE                      # MIT License
+└── README.md
+```
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for details.
+
+---
+
+## Key Review Notes
+
+* Verify the GitHub Actions workflow file path (`.github/workflows/tests.yml`) matches your actual workflow file name so the build badge renders correctly.
+* In the `repopy init` theme section, verify that the theme descriptions match what you have mapped out in `templates.py`.

repopy-0.2.0/README.md

@@ -0,0 +1,151 @@
+# repopy
+
+A modular, cross-platform Python CLI workspace manager and developer tooling suite designed to automate reproducible local scaffolding, virtual environment creation, and remote repository synchronization.
+
+![PyPI - Version](https://img.shields.io/pypi/v/repopy?color=orange)   
+[![CI](https://github.com/manatunga/repopy/actions/workflows/tests.yml/badge.svg)](https://github.com/manatunga/repopy/actions/workflows/tests.yml)   
+[![Python Versions](https://img.shields.io/pypi/pyversions/repopy.svg)](https://pypi.org)   
+[![License: MIT](https://img.shields.io/pypi/l/repopy.svg)](https://opensource.org/license/mit)
+
+---
+
+## 🌟 Key Features
+
+- **Lifecycle Project Scaffolding (`repopy init`)**: Replaces manual setup by provisioning clean directory structures, virtual environments, automated `.gitignore` presets, and standardized metadata configurations (`pyproject.toml` or `requirements.txt`).
+
+- **Remote Cloning (`repopy clone`)**: Clones remote Git repositories into structured local footprints and auto-provisions dedicated virtual environments and dependencies.
+
+- **Upstream Linking (`repopy link`)**: Instantly connects an unlinked local workspace to a remote Git upstream, staging files, executing initial commits, and pushing to the default branch in one step.
+
+- **Architectural Themes**: Supports presets (`minimal`, `web_api`, `cli_package`, `data_science`) tailored to the specific packaging needs of the application.
+
+- **Transactional Cleanups**: Employs defensive rollback mechanisms (`shutil.rmtree`) to purge incomplete workspaces if initialization fails midway.
+
+- **Automated Test Suite & CI**: Fully covered by local `pytest` test suites and verified via continuous integration on GitHub Actions.
+
+---
+
+## 🛠️ Architecture & Separation of Concerns
+
+`repopy` is organized into single-responsibility layers:
+- **Presentation & Routing (`cli.py`, `prompts.py`, `__main__.py`)**: Evaluates native terminal arguments via `argparse`, orchestrates interactive prompt flows, and handles OS interrupts gracefully.
+
+- **Supervision (`orchestrators.py`)**: Broker layer executing lifecycle validation checks, branch sequencing, and command handoffs.
+
+- **Low-Level Engines (`file_system.py`, `git_engine.py`)**: Decoupled engines handling transactional directory allocations, venv isolation, and direct subprocess execution.
+
+- **Validation & Translation (`validators.py`, `dependencies.py`, `os_detector.py`)**: Sanitizes paths, ensures semantic regex compliance, verifies system binaries (such as `git`), and resolves cross-platform paths.
+
+---
+
+## 📥 Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install repopy
+```
+Alternatively, you can install the latest development version directly from the source:
+
+```bash
+git clone https://github.com/manatunga/repopy.git
+cd repopy
+pip install -e .
+```
+
+---
+
+## 🚀 Usage Guide
+
+### 1. Initialize a Project (`repopy init`)
+Generate a new workspace interactively or via CLI flags:
+
+```bash
+# Interactive setup
+repopy init my-app
+
+# Non-interactive generation with a specific theme
+repopy init my-api -t web_api -s
+
+# Initialize and immediately connect to a remote repository
+repopy init my-cli -t cli_package --link <git-url>
+```
+
+#### Available Themes:
+- `minimal`: Bare directory setup with `requirements.txt`.
+- `web_api`: Layered service layout prepared for modern frameworks.
+- `cli_package`: Modular structure configured with PEP 621 compliant `pyproject.toml`.
+- `data_science`: Notebooks, data folders, and pipeline layouts.
+<br>
+<br>
+
+### 2. Clone a Remote Project (`repopy clone`)
+Fetch a remote repository and immediately auto-provision an isolated `.venv`:
+
+```bash
+repopy clone <git-url> -n [custom-project-name]
+```
+
+<br>
+
+### 3. Link an Existing Workspace (`repopy link`)
+Run inside an existing workspace to push tracking history to an upstream origin:
+
+```bash
+repopy link <git-url> -m ["custom-initial-commit-message"]
+```
+
+---
+
+## 🧪 Testing & Continuous Integration
+
+Run the test suite using `pytest`:
+
+```bash
+pytest -v
+```
+
+All contributions and pull requests are validated through our GitHub Actions workflow matrix (`.github/workflows/tests.yml`), running integration and validation tests across supported Python versions.
+
+---
+
+## 🗂️ Project Structure
+
+```
+repopy/
+├── .github/
+│   └── workflows/
+│       └── tests.yml            # CI test runner pipeline
+├── src/
+│   └── repopy/
+│       ├── __init__.py          # Package initialization
+│       ├── __main__.py          # Application execution entry
+│       ├── cli.py               # CLI subparser configuration
+│       ├── dependencies.py      # Binary prerequisite verification
+│       ├── file_system.py       # Atomic workspace & venv operations
+│       ├── git_engine.py        # Subprocess Git execution engine
+│       ├── orchestrators.py     # High-level pipeline management
+│       ├── os_detector.py       # Cross-platform environment resolver
+│       ├── prompts.py           # Dynamic terminal questionnaires
+│       ├── templates.py         # Static asset definitions & manifests
+│       └── validators.py        # Input sanitation & regex filters
+├── tests/
+│   ├── test_prompts.py          # Input loop & default manifest tests
+│   └── test_validators.py       # Path and schema validation tests
+├── pyproject.toml               # PEP 621 packaging configuration
+├── LICENSE                      # MIT License
+└── README.md
+```
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for details.
+
+---
+
+## Key Review Notes
+
+* Verify the GitHub Actions workflow file path (`.github/workflows/tests.yml`) matches your actual workflow file name so the build badge renders correctly.
+* In the `repopy init` theme section, verify that the theme descriptions match what you have mapped out in `templates.py`.

repopy-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "repopy"
+version = "0.2.0"
+description = "A modular CLI workspace initializer and cloning automation tool."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+
+authors = [
+    {name = "Janitha Manatunga", email = "janithamanatunga@gmail.com"}
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://github.com/manatunga/repopy"
+Repository = "https://github.com/manatunga/repopy"
+"Bug Tracker" = "https://github.com/manatunga/repopy/issues"
+
+[project.scripts]
+repopy = "repopy.__main__:main"

repopy-0.2.0/src/repopy/__main__.py

@@ -0,0 +1,45 @@
+'''
+Main entrypoint of repopy. Brings together the argument parser and
+the orchestrators together under a main function.
+'''
+import sys
+from repopy.cli import parse_arguments
+from repopy.prompts import capture_project_manifests
+from repopy.orchestrators import LocalInitializer, CloneInitializer, LinkInitializer
+
+def main() -> None:
+    try:
+        args = parse_arguments()
+
+        if args.command == 'init':
+            print('Working on it...\n')
+            manifest = capture_project_manifests(args)
+            initializer = LocalInitializer(manifest)
+            success = initializer.run()
+
+            if success and args.link:
+                print('Initiating automated repository link shortcut...')
+                link_initializer = LinkInitializer(args.link, args.message)
+                link_initializer.run()
+
+        elif args.command == 'clone':
+            print('Working on it...\n')
+            initializer = CloneInitializer(args.repo_url, args.name)
+            initializer.run()
+
+        elif args.command == 'link':
+            print('Working on it...\n')
+            initializer = LinkInitializer(args.repo_url, args.message)
+            initializer.run()
+
+        else:
+            print('Usage: repopy [local | clone] --help')
+            print('Error: Please specify a subcommand')
+
+    except KeyboardInterrupt:
+        print('\n Workspace operation cancelled by user.')
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

repopy-0.2.0/src/repopy/cli.py

@@ -0,0 +1,99 @@
+'''
+Parser layer. Imports Python's built-in argparse module 
+to identify user intent and any extra information passed. 
+'''
+
+import argparse
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description='repopy: A modular project scaffolder and workflow manager for Python.'
+    )
+    
+    subparsers = parser.add_subparsers(dest='command', required=True)
+
+    #---------------------------------------------------------------------------------
+    # `repopy init` subcommand
+    #---------------------------------------------------------------------------------
+
+    init_parser = subparsers.add_parser(
+        'init',
+        help='Initializes a standardized Python development workspace in a new directory'
+    )
+
+    # Optional argument to add a project_name
+    init_parser.add_argument(
+        'project_name',
+        nargs='?',
+        help='Name of the target project folder to create'
+    )
+
+    # Project theme shortcut flag (-t / --theme)
+    init_parser.add_argument(
+        '-t', '--theme',
+        choices=['minimal', 'web_api', 'cli_package', 'data_science'],
+        help='Pre-select an architectural theme layout'
+    )
+
+    # Skip flag (-s / --skip) to bypass input prompts completely
+    init_parser.add_argument(
+        '-s', '--skip',
+        action='store_true',
+        help='Skip interactive loops and generate workspace using default values'
+    )
+
+    # Link flag (-l / --link) to pass an existing remote URL during creation
+    init_parser.add_argument(
+        '-l', '--link',
+        metavar='GIT_URL',
+        help='Automatically link and push the new local repo to this remote Git URL'
+    )
+
+    # Custom commit message shortcut allowed directly during init orchestration
+    init_parser.add_argument(
+        '-m', '--message',
+        help='Custom commit message to use for the initial repository push'
+    )
+
+    #---------------------------------------------------------------------------------
+    # `repopy clone` subcommand
+    #---------------------------------------------------------------------------------
+
+    clone_parser = subparsers.add_parser(
+        'clone',
+        help='Clones a remote Git repository to the local machine'
+    )
+
+    # Positional argument to add remote Git URL
+    clone_parser.add_argument(
+        'repo_url', 
+        help='Repository URL from Github to clone locally'
+    )
+
+    # Name flag (-n / --name) to pass an optional name for the to-be-cloned repository
+    clone_parser.add_argument(
+        '-n', '--name',
+        help='Name of the project folder'
+    )
+
+    #---------------------------------------------------------------------------------
+    # `repopy link` subcommand
+    #---------------------------------------------------------------------------------
+
+    link_parser = subparsers.add_parser(
+        'link',
+        help='Stage, commit and link current local repository to a remote Git URL'
+    )
+
+    # Positional argument to add a dedicated existing remote Git URL for the local repository
+    link_parser.add_argument(
+        'repo_url',
+        help='Target remote Git repository URL (e.g., git@github.com:user/repo.git)'
+    )
+
+    link_parser.add_argument(
+        '-m', '--message',
+        help='Custom commit message to use instead of the default repopy message'
+    )  
+
+    return parser.parse_args()

{repopy-0.1.0 → repopy-0.2.0}/src/repopy/file_system.py

@@ -10,30 +10,12 @@ import logging
 import subprocess
 from pathlib import Path
 
+from repopy.templates import GITIGNORE_TEMPLATE, generate_pyproject_toml
+
 logger = logging.getLogger(__name__)
 
 class FileSystemEngine:
 
-    GITIGNORE_TEMPLATE = '''# Compiled Python files
-__pycache__/
-*.pyc
- 
-# Virtual environments
-# .venv/
-venv/
-env/
-ENV/
-
-# IDEs and Editors
-.vscode/
-.idea/
-*.swp
-*.swo
-    
-# OS files
-.DS_Store
-Thumbs_db'''
-
     def __init__(self, project_path: Path):
         self.project_path = project_path
 
@@ -49,17 +31,54 @@ Thumbs_db'''
             return False
 
 
-    def create_gitignore(self) -> bool:
-        '''Generates a .gitignore file with a basic python gitignore template'''
-        gitignore_file = self.project_path / '.gitignore'
+    def create_theme_directories(self, theme: str, project_name: str):
+        '''Maps and structures the child directory tree based on the project theme'''
+        if theme == 'web_api':
+            sub_dirs = ['src/app', 'src/app/routes', 'src/app/models']
+
+        elif theme == 'cli_package':
+            sub_dirs = [f'src/{project_name}', 'tests']
+
+        elif theme == 'data_science':
+            sub_dirs = ['data/raw', 'data/processed', 'notebooks', 'src/pipeline']
+
+        else:
+            return True
 
         try:
-            with open(gitignore_file, 'w') as f:
-                f.write(self.GITIGNORE_TEMPLATE)
-                return True
-            
+            for folder in sub_dirs:
+                target_folder_path = (self.project_path / folder).resolve()
+                target_folder_path.mkdir(parents=True, exist_ok=True)
+
+            return True
+
+        except OSError as e:
+            logger.error(f'Failed to build nested structures for theme {theme}: {e}')
+            return False
+
+
+    def write_theme_configurations(self, theme: str, manifest: dict) -> bool:
+        '''Deploys standard configuration templates (gitignore, requirements.txt or toml)'''
+        try:
+            gitignore_path = self.project_path / '.gitignore'
+            with open(gitignore_path, 'w') as f:
+                f.write(GITIGNORE_TEMPLATE)
+
+            if theme == 'minimal':
+                req_path = self.project_path / 'requirements.txt'
+                with open(req_path, 'w') as f:
+                    f.write('')
+
+            else:
+                toml_content = generate_pyproject_toml(manifest)
+                toml_path = self.project_path / 'pyproject.toml'
+                with open(toml_path, 'w') as f:
+                    f.write(toml_content)
+
+            return True
+
         except OSError as e:
-            logger.error(f'Failed to create gitignore file at {self.project_path}: {e}')
+            logger.error(f'Failed to deploy structural file sheets: {e}')
             return False
 
 
@@ -96,13 +115,14 @@ Thumbs_db'''
                 logger.error(f'Failed to clean up directory at {self.project_path}: {e}')
 
 
-    def build_workspace(self) -> bool:
+    def build_workspace(self, theme: str, manifest: dict) -> bool:
         '''Orchestrate entire file-system creation sequence'''
 
         if self.create_root_directory():
             if self.initialize_git():
-                if self.create_gitignore():
-                    if self.create_virtual_environment():
-                        return True
+                if self.create_theme_directories(theme, manifest['project_name']):
+                    if self.write_theme_configurations(theme, manifest):
+                        if self.create_virtual_environment():
+                            return True
 
         return False

{repopy-0.1.0 → repopy-0.2.0}/src/repopy/git_engine.py

@@ -61,4 +61,42 @@ class GitEngine:
                 logger.info(f'Successfully cleaned up half-baked workspace at {self.project_path}')
             except OSError as e:
                 logger.error(f'Failed to clean up directory at {self.project_path}: {e}')
-    
+
+
+class GitLinkEngine:
+
+    def __init__(self, repo_url: str, message: str):
+        self.repo_url = repo_url
+        self.message = message
+
+
+    def link_and_push(self) -> bool:
+        '''Runs the sequence of Git terminal execution blocks to link the repo'''
+        try:
+            stage_result = subprocess.run(['git', 'add', '.'], capture_output=True, text=True)
+            if stage_result.returncode != 0:
+                return False
+
+            commit_result = subprocess.run(['git', 'commit', '-m', self.message], capture_output=True, text=True)
+            if commit_result.returncode != 0:
+                if 'nothing to commit' not in commit_result.stdout:
+                    return False
+
+            branch_result = subprocess.run(['git', 'branch', '-M', 'main'], capture_output=True, text=True)
+            if branch_result.returncode != 0:
+                return False
+
+            remote_result = subprocess.run(['git', 'remote', 'add', 'origin', self.repo_url], capture_output=True, text=True)
+            if remote_result.returncode != 0:
+                return False
+
+            push_result = subprocess.run(['git', 'push', '-u', 'origin', 'main'], text=True)
+            if push_result.returncode != 0:
+                return False
+
+            return True
+
+        except OSError as e:
+            logger.error(f'Failed to execute Git linking operationsL {e}')
+            return False
+