Yuvacodes 0.1.0__py3-none-any.whl

mycodes/__init__.py

@@ -0,0 +1,42 @@
+"""MyCodes: Personal cloud-based code library for Python and Jupyter Notebooks."""
+
+from mycodes.config import configure, get_config
+from mycodes.registry import get_code, get_info, list_codes, search, run
+from mycodes.exceptions import (
+    MyCodesError,
+    CodeNotFoundError,
+    RepositoryNotFoundError,
+    ConfigurationError,
+    RemoteFetchError,
+    ExecutionDisabledError,
+)
+from mycodes.jupyter_extension import load_ipython_extension, unload_ipython_extension
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "configure",
+    "get_config",
+    "get_code",
+    "get_info",
+    "list_codes",
+    "search",
+    "run",
+    "MyCodesError",
+    "CodeNotFoundError",
+    "RepositoryNotFoundError",
+    "ConfigurationError",
+    "RemoteFetchError",
+    "ExecutionDisabledError",
+    "load_ipython_extension",
+    "unload_ipython_extension",
+]
+
+# Auto-register IPython extension if running inside an active IPython session
+try:
+    from IPython import get_ipython
+    _ip = get_ipython()
+    if _ip is not None:
+        load_ipython_extension(_ip)
+except Exception:
+    pass

mycodes/cli.py

@@ -0,0 +1,137 @@
+"""Command-line interface (CLI) for the MyCodes package."""
+
+import argparse
+import sys
+from mycodes.config import configure, get_config
+from mycodes.exceptions import MyCodesError
+from mycodes.registry import get_code, get_info, list_codes, search, run
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="mycodes",
+        description="MyCodes - Your personal cloud-based code library CLI.",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Command: list
+    list_p = subparsers.add_parser("list", help="List all available codes in the cloud library.")
+    list_p.add_argument("--refresh", "-r", action="store_true", help="Force refresh index from GitHub.")
+
+    # Command: get
+    get_p = subparsers.add_parser("get", help="Retrieve source code for a specific ID.")
+    get_p.add_argument("id", help="The numeric or string code ID (e.g., 101 or 001).")
+    get_p.add_argument("--cache", "-c", action="store_true", help="Cache the code locally.")
+    get_p.add_argument("--refresh", "-r", action="store_true", help="Force refresh from GitHub.")
+
+    # Command: info
+    info_p = subparsers.add_parser("info", help="Show metadata information for a code snippet.")
+    info_p.add_argument("id", help="The code ID.")
+    info_p.add_argument("--refresh", "-r", action="store_true", help="Force refresh from GitHub.")
+
+    # Command: search
+    search_p = subparsers.add_parser("search", help="Search codes by keyword, category, or language.")
+    search_p.add_argument("query", nargs="?", default=None, help="Search keyword.")
+    search_p.add_argument("--category", "-c", default=None, help="Filter by category.")
+    search_p.add_argument("--language", "-l", default=None, help="Filter by language.")
+
+    # Command: config
+    cfg_p = subparsers.add_parser("config", help="View or update MyCodes repository configuration.")
+    cfg_p.add_argument("--username", "-u", default=None, help="GitHub username.")
+    cfg_p.add_argument("--repository", "-r", default=None, help="Repository name.")
+    cfg_p.add_argument("--branch", "-b", default=None, help="Branch name.")
+
+    # Command: run
+    run_p = subparsers.add_parser("run", help="Execute remote code (requires explicit opt-in).")
+    run_p.add_argument("id", help="The code ID to execute.")
+    run_p.add_argument(
+        "--allow-execution",
+        action="store_true",
+        help="Explicitly acknowledge and allow execution of remote code.",
+    )
+
+    return parser
+
+
+def main(args=None) -> int:
+    """CLI entry point function."""
+    parser = build_parser()
+    parsed = parser.parse_args(args)
+
+    if not parsed.command:
+        parser.print_help()
+        return 0
+
+    try:
+        if parsed.command == "list":
+            list_codes(return_data=False, refresh=parsed.refresh)
+            return 0
+
+        elif parsed.command == "get":
+            code = get_code(parsed.id, cache=parsed.cache, refresh=parsed.refresh)
+            print(code, end="")
+            if not code.endswith("\n"):
+                print()
+            return 0
+
+        elif parsed.command == "info":
+            info = get_info(parsed.id, refresh=parsed.refresh)
+            print(f"ID:          {info.get('id')}")
+            print(f"Name:        {info.get('name', 'N/A')}")
+            print(f"Description: {info.get('description', 'N/A')}")
+            print(f"Category:    {info.get('category', 'N/A')}")
+            print(f"Language:    {info.get('language', 'python')}")
+            if "tags" in info and info["tags"]:
+                tags_str = ", ".join(info["tags"]) if isinstance(info["tags"], list) else str(info["tags"])
+                print(f"Tags:        {tags_str}")
+            print(f"File:        {info.get('file', 'N/A')}")
+            return 0
+
+        elif parsed.command == "search":
+            search(
+                query=parsed.query,
+                category=parsed.category,
+                language=parsed.language,
+                return_data=False,
+            )
+            return 0
+
+        elif parsed.command == "config":
+            if parsed.username or parsed.repository or parsed.branch:
+                configure(
+                    username=parsed.username,
+                    repository=parsed.repository,
+                    branch=parsed.branch,
+                    persist=True,
+                )
+                print("Configuration saved to ~/.mycodes/config.json:")
+            current = get_config().to_dict()
+            print(f"  Username:   {current.get('username') or '(not set)'}")
+            print(f"  Repository: {current.get('repository')}")
+            print(f"  Branch:     {current.get('branch')}")
+            return 0
+
+        elif parsed.command == "run":
+            if not parsed.allow_execution:
+                print(
+                    "Error: Remote code execution is disabled by default for security.\n"
+                    "Use --allow-execution to run this code.",
+                    file=sys.stderr,
+                )
+                return 1
+            run(parsed.id, allow_execution=True)
+            return 0
+
+    except MyCodesError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mycodes/client.py

@@ -0,0 +1,174 @@
+"""HTTP client and caching layer for interacting with remote GitHub repository."""
+
+import hashlib
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Dict, Any, Optional
+from mycodes.config import Config, get_config
+from mycodes.exceptions import (
+    RepositoryNotFoundError,
+    RemoteFetchError,
+)
+
+USER_AGENT = "MyCodes-Python-Client/0.1.0"
+INDEX_CACHE_TTL = 300  # 5 minutes default in-memory TTL
+
+
+class GitHubClient:
+    """Handles communication with GitHub raw content and manages caching."""
+
+    def __init__(self, config: Optional[Config] = None):
+        self._config = config
+        self._index_cache: Optional[Dict[str, Any]] = None
+        self._index_fetched_at: float = 0.0
+
+    @property
+    def config(self) -> Config:
+        return self._config or get_config()
+
+    def fetch_url(self, url: str) -> str:
+        """Fetch raw text content from a given URL with timeout and custom headers."""
+        headers = {
+            "User-Agent": USER_AGENT,
+            "Accept": "text/plain, application/json, */*",
+        }
+        req = urllib.request.Request(url, headers=headers)
+        timeout = self.config.get_timeout()
+
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as response:
+                content_bytes = response.read()
+                return content_bytes.decode("utf-8")
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                # 404 handled specifically by caller if needed
+                raise e
+            elif e.code == 403:
+                raise RemoteFetchError(
+                    f"GitHub API/Raw rate limit exceeded or access forbidden (HTTP 403) at {url}."
+                ) from e
+            elif e.code >= 500:
+                raise RemoteFetchError(
+                    f"GitHub server error (HTTP {e.code}) while requesting {url}."
+                ) from e
+            else:
+                raise RemoteFetchError(
+                    f"HTTP error {e.code} ({e.reason}) while requesting {url}."
+                ) from e
+        except urllib.error.URLError as e:
+            raise RemoteFetchError(
+                f"Network connection failed: {e.reason} while requesting {url}."
+            ) from e
+        except TimeoutError as e:
+            raise RemoteFetchError(
+                f"Connection timed out after {timeout} seconds while requesting {url}."
+            ) from e
+        except Exception as e:
+            raise RemoteFetchError(
+                f"Unexpected error while fetching {url}: {str(e)}"
+            ) from e
+
+    def fetch_index(self, refresh: bool = False) -> Dict[str, Any]:
+        """
+        Fetch and parse index.json from the configured GitHub repository.
+        Uses in-memory cache unless expired or refresh=True.
+        """
+        now = time.time()
+        if (
+            not refresh
+            and self._index_cache is not None
+            and (now - self._index_fetched_at) < INDEX_CACHE_TTL
+        ):
+            return self._index_cache
+
+        url = self.config.get_raw_url("index.json")
+        try:
+            raw_data = self.fetch_url(url)
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                raise RepositoryNotFoundError(
+                    username=self.config.username,
+                    repository=self.config.get_repository(),
+                    branch=self.config.get_branch(),
+                ) from e
+            raise
+
+        try:
+            parsed = json.loads(raw_data)
+        except json.JSONDecodeError as e:
+            raise RemoteFetchError(
+                f"Failed to parse index.json from {url}: Invalid JSON structure ({str(e)})."
+            ) from e
+
+        if not isinstance(parsed, dict):
+            raise RemoteFetchError(
+                f"Invalid index.json schema from {url}: Expected root object (dict), got {type(parsed).__name__}."
+            )
+
+        self._index_cache = parsed
+        self._index_fetched_at = now
+        return parsed
+
+    def fetch_code(self, file_path: str, cache: bool = False, refresh: bool = False) -> str:
+        """
+        Fetch source code file from GitHub.
+        If cache=True, caches locally to avoid repeated downloads.
+        """
+        cache_file = None
+        if cache:
+            cache_dir = self.config.cache_dir
+            cache_dir.mkdir(parents=True, exist_ok=True)
+            # Create a deterministic filename based on url
+            cache_key = hashlib.sha256(file_path.encode("utf-8")).hexdigest()
+            cache_file = cache_dir / f"{cache_key}.py"
+
+            if not refresh and cache_file.exists():
+                try:
+                    with open(cache_file, "r", encoding="utf-8") as f:
+                        return f.read()
+                except Exception:
+                    # On cache read failure, fall back to remote fetch
+                    pass
+
+        url = self.config.get_raw_url(file_path)
+        try:
+            code = self.fetch_url(url)
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                raise RemoteFetchError(
+                    f"Code file '{file_path}' was not found at {url} (HTTP 404)."
+                ) from e
+            raise
+
+        if cache and cache_file is not None:
+            try:
+                with open(cache_file, "w", encoding="utf-8") as f:
+                    f.write(code)
+            except Exception:
+                # Cache write error should not fail the user's operation
+                pass
+
+        return code
+
+    def clear_cache(self) -> None:
+        """Clear both in-memory index cache and disk cache."""
+        self._index_cache = None
+        self._index_fetched_at = 0.0
+        cache_dir = self.config.cache_dir
+        if cache_dir.exists():
+            for f in cache_dir.glob("*.py"):
+                try:
+                    f.unlink()
+                except Exception:
+                    pass
+
+
+# Default singleton client
+_DEFAULT_CLIENT = GitHubClient()
+
+
+def get_client() -> GitHubClient:
+    """Return default singleton client."""
+    return _DEFAULT_CLIENT

mycodes/config.py

@@ -0,0 +1,192 @@
+"""Configuration management for the MyCodes library."""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any
+from mycodes.exceptions import ConfigurationError
+
+CONFIG_DIR = Path.home() / ".mycodes"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+DEFAULT_REPOSITORY = "my-code-library"
+DEFAULT_BRANCH = "main"
+DEFAULT_TIMEOUT = 10.0
+
+
+class Config:
+    """Holds configuration state for MyCodes."""
+
+    def __init__(
+        self,
+        username: Optional[str] = None,
+        repository: Optional[str] = None,
+        branch: Optional[str] = None,
+        cache_dir: Optional[Path] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self._username = username
+        self._repository = repository
+        self._branch = branch
+        self.cache_dir = cache_dir or (CONFIG_DIR / "cache")
+        self.timeout = timeout
+
+    @property
+    def username(self) -> str:
+        """Get the configured GitHub username or raise ConfigurationError."""
+        # 1. In-memory explicit setting
+        if self._username:
+            return self._username
+
+        # 2. Environment variable
+        env_user = os.environ.get("MYCODES_GITHUB_USER")
+        if env_user:
+            return env_user
+
+        # 3. Persistent config file
+        file_config = self._load_file_config()
+        if "username" in file_config and file_config["username"]:
+            return file_config["username"]
+
+        raise ConfigurationError(
+            "GitHub username is not configured. Please configure it via:\n"
+            "  1. configure(username='YOUR_GITHUB_USERNAME') in Python\n"
+            "  2. Setting the MYCODES_GITHUB_USER environment variable\n"
+            "  3. Running 'mycodes config --username YOUR_GITHUB_USERNAME' in your terminal."
+        )
+
+    @username.setter
+    def username(self, val: Optional[str]):
+        self._username = val
+
+    @property
+    def repository(self) -> str:
+        return self.get_repository()
+
+    @repository.setter
+    def repository(self, val: Optional[str]):
+        self._repository = val
+
+    @property
+    def branch(self) -> str:
+        return self.get_branch()
+
+    @branch.setter
+    def branch(self, val: Optional[str]):
+        self._branch = val
+
+    def get_repository(self) -> str:
+        """Get the configured repository name."""
+        if self._repository:
+            return self._repository
+        env_repo = os.environ.get("MYCODES_GITHUB_REPO")
+        if env_repo:
+            return env_repo
+        file_config = self._load_file_config()
+        return file_config.get("repository", DEFAULT_REPOSITORY)
+
+    def get_branch(self) -> str:
+        """Get the configured branch name."""
+        if self._branch:
+            return self._branch
+        env_branch = os.environ.get("MYCODES_GITHUB_BRANCH")
+        if env_branch:
+            return env_branch
+        file_config = self._load_file_config()
+        return file_config.get("branch", DEFAULT_BRANCH)
+
+    def get_timeout(self) -> float:
+        """Get network timeout in seconds."""
+        env_timeout = os.environ.get("MYCODES_TIMEOUT")
+        if env_timeout:
+            try:
+                return float(env_timeout)
+            except ValueError:
+                pass
+        return self.timeout
+
+    def get_raw_url(self, path: str) -> str:
+        """Construct raw GitHub URL for a given repository relative path."""
+        user = self.username
+        repo = self.get_repository()
+        branch = self.get_branch()
+        clean_path = path.lstrip("/")
+        return f"https://raw.githubusercontent.com/{user}/{repo}/{branch}/{clean_path}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return configuration as a dictionary."""
+        return {
+            "username": self._username or os.environ.get("MYCODES_GITHUB_USER") or self._load_file_config().get("username"),
+            "repository": self.get_repository(),
+            "branch": self.get_branch(),
+            "timeout": self.get_timeout(),
+            "cache_dir": str(self.cache_dir),
+        }
+
+    def _load_file_config(self) -> Dict[str, Any]:
+        """Load stored config from disk if exists."""
+        if CONFIG_FILE.exists():
+            try:
+                with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except Exception:
+                return {}
+        return {}
+
+    def save_to_file(self) -> None:
+        """Save active config to ~/.mycodes/config.json."""
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        data = {
+            "username": self._username,
+            "repository": self.repository,
+            "branch": self.branch,
+        }
+        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+
+# Global singleton instance
+_GLOBAL_CONFIG = Config()
+
+
+def get_config() -> Config:
+    """Return the active global configuration."""
+    return _GLOBAL_CONFIG
+
+
+def configure(
+    username: Optional[str] = None,
+    repository: Optional[str] = None,
+    branch: Optional[str] = None,
+    timeout: Optional[float] = None,
+    persist: bool = False,
+) -> Config:
+    """
+    Configure the MyCodes client.
+
+    Args:
+        username: GitHub username/organization owning the repository.
+        repository: Name of the repository (defaults to 'my-code-library').
+        branch: Git branch name (defaults to 'main').
+        timeout: Network timeout in seconds (defaults to 10.0).
+        persist: If True, writes settings to ~/.mycodes/config.json.
+    """
+    if username is not None:
+        _GLOBAL_CONFIG.username = username
+    if repository is not None:
+        _GLOBAL_CONFIG.repository = repository
+    if branch is not None:
+        _GLOBAL_CONFIG.branch = branch
+    if timeout is not None:
+        _GLOBAL_CONFIG.timeout = timeout
+
+    if persist:
+        _GLOBAL_CONFIG.save_to_file()
+
+    return _GLOBAL_CONFIG
+
+
+def reset_config() -> None:
+    """Reset configuration to defaults (useful for testing)."""
+    global _GLOBAL_CONFIG
+    _GLOBAL_CONFIG = Config()

mycodes/exceptions.py

@@ -0,0 +1,54 @@
+"""Custom exceptions for the MyCodes library."""
+
+
+class MyCodesError(Exception):
+    """Base exception for all MyCodes errors."""
+    pass
+
+
+class CodeNotFoundError(MyCodesError):
+    """Raised when a requested code ID cannot be found in the repository."""
+
+    def __init__(self, code_id: str or int, message: str = None):
+        self.code_id = code_id
+        if message is None:
+            message = f"Code {code_id} was not found in the MyCodes repository."
+        super().__init__(message)
+
+
+class RepositoryNotFoundError(MyCodesError):
+    """Raised when the remote GitHub repository, branch, or index cannot be accessed."""
+
+    def __init__(self, username: str, repository: str, branch: str = "main", message: str = None):
+        self.username = username
+        self.repository = repository
+        self.branch = branch
+        if message is None:
+            message = (
+                f"Repository '{username}/{repository}' on branch '{branch}' was not found on GitHub "
+                f"or index.json is missing."
+            )
+        super().__init__(message)
+
+
+class ConfigurationError(MyCodesError):
+    """Raised when required configuration settings are missing or invalid."""
+    pass
+
+
+class RemoteFetchError(MyCodesError):
+    """Raised when a network failure, timeout, or HTTP error occurs while fetching remote code."""
+    pass
+
+
+class ExecutionDisabledError(MyCodesError):
+    """Raised when code execution is attempted without explicit authorization."""
+
+    def __init__(
+        self,
+        message: str = (
+            "Remote code execution is disabled by default for security. "
+            "Pass allow_execution=True to execute retrieved code."
+        ),
+    ):
+        super().__init__(message)