python-package-folder 0.1.0__py3-none-any.whl

python_package_folder/manager.py

@@ -0,0 +1,388 @@
+"""
+Build management functionality.
+
+This module provides the BuildManager class which orchestrates the entire
+build process: finding external dependencies, copying them temporarily,
+running the build command, and cleaning up afterward.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:
+    try:
+        import tomli as tomllib
+    except ImportError:
+        tomllib = None
+
+from .analyzer import ImportAnalyzer
+from .finder import ExternalDependencyFinder
+from .types import ExternalDependency, ImportInfo
+
+
+class BuildManager:
+    """
+    Manages the build process with external dependency handling.
+
+    This is the main class for using the package. It coordinates finding
+    external dependencies, copying them into the source directory, running
+    the build, and cleaning up.
+
+    Attributes:
+        project_root: Root directory of the project
+        src_dir: Source directory containing the package code
+        copied_files: List of file paths that were copied (for cleanup)
+        copied_dirs: List of directory paths that were copied (for cleanup)
+    """
+
+    def __init__(self, project_root: Path, src_dir: Path | None = None) -> None:
+        """
+        Initialize the build manager.
+
+        Args:
+            project_root: Root directory of the project
+            src_dir: Source directory (defaults to project_root/src)
+
+        Raises:
+            ValueError: If the source directory does not exist
+        """
+        self.project_root = project_root.resolve()
+        self.src_dir = src_dir or (self.project_root / "src")
+        if not self.src_dir.exists():
+            raise ValueError(f"Source directory not found: {self.src_dir}")
+
+        self.copied_files: list[Path] = []
+        self.copied_dirs: list[Path] = []
+
+    def find_src_package_dir(self) -> Path | None:
+        """
+        Find the main package directory within src/.
+
+        Looks for directories with __init__.py files. If multiple are found,
+        tries to match one with the project name from pyproject.toml.
+
+        Returns:
+            Path to the main package directory, or src_dir if not found
+        """
+        if not self.src_dir.exists():
+            return None
+
+        # Look for directories with __init__.py
+        package_dirs = [
+            d for d in self.src_dir.iterdir() if d.is_dir() and (d / "__init__.py").exists()
+        ]
+
+        if len(package_dirs) == 1:
+            return package_dirs[0]
+
+        # If multiple, try to find the one matching the project name
+        project_name = self._get_project_name()
+        if project_name:
+            for pkg_dir in package_dirs:
+                if pkg_dir.name.replace("-", "_") == project_name.replace("-", "_"):
+                    return pkg_dir
+
+        # Return the first one or src_dir itself
+        return package_dirs[0] if package_dirs else self.src_dir
+
+    def _get_project_name(self) -> str | None:
+        """
+        Get the project name from pyproject.toml.
+
+        Uses tomllib (Python 3.11+) or tomli as fallback to parse the file.
+        Falls back to simple string parsing if TOML parsing is unavailable.
+
+        Returns:
+            Project name from pyproject.toml, or None if not found
+        """
+        pyproject_path = self.project_root / "pyproject.toml"
+        if not pyproject_path.exists():
+            return None
+
+        try:
+            if tomllib:
+                content = pyproject_path.read_bytes()
+                data = tomllib.loads(content)
+                return data.get("project", {}).get("name")
+            else:
+                # Fallback: simple parsing
+                content = pyproject_path.read_text(encoding="utf-8")
+                for line in content.split("\n"):
+                    if line.strip().startswith("name ="):
+                        return line.split("=", 1)[1].strip().strip('"').strip("'")
+        except Exception:
+            pass
+
+        return None
+
+    def prepare_build(self) -> list[ExternalDependency]:
+        """
+        Prepare for build by finding and copying external dependencies.
+
+        This method:
+        1. Finds all Python files in the source directory
+        2. Analyzes them for external dependencies
+        3. Copies external files/directories into the source directory
+        4. Reports any ambiguous imports
+
+        Returns:
+            List of ExternalDependency objects that were copied
+        """
+        analyzer = ImportAnalyzer(self.project_root)
+        finder = ExternalDependencyFinder(self.project_root, self.src_dir)
+
+        # Find all Python files in src/
+        python_files = analyzer.find_all_python_files(self.src_dir)
+
+        # Find external dependencies
+        external_deps = finder.find_external_dependencies(python_files)
+
+        # Copy external dependencies
+        for dep in external_deps:
+            self._copy_dependency(dep)
+
+        # Report ambiguous imports
+        self._report_ambiguous_imports(python_files)
+
+        return external_deps
+
+    def _copy_dependency(self, dep: ExternalDependency) -> None:
+        """
+        Copy an external dependency to the target location.
+
+        Handles both files and directories. Checks for idempotency to avoid
+        duplicate copies. Creates parent directories as needed.
+
+        Args:
+            dep: ExternalDependency object with source and target paths
+        """
+        source = dep.source_path
+        target = dep.target_path
+
+        if not source.exists():
+            print(f"Warning: External dependency not found: {source}", file=sys.stderr)
+            return
+
+        # Create target directory if needed
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        # Check if already copied (idempotency)
+        if target.exists():
+            # Check if it's the same file
+            if source.is_file() and target.is_file():
+                try:
+                    if source.samefile(target):
+                        return  # Already in place, skip
+                except OSError:
+                    # Files are different, proceed with copy
+                    pass
+            elif source.is_dir() and target.is_dir():
+                # For directories, check if they have the same structure
+                # Simple check: if target has __init__.py and source does too, assume copied
+                # Also check if target has any Python files
+                source_has_init = (source / "__init__.py").exists()
+                target_has_init = (target / "__init__.py").exists()
+                if source_has_init == target_has_init:
+                    # Check if target has at least some files from source
+                    source_files = {f.name for f in source.rglob("*.py")}
+                    target_files = {f.name for f in target.rglob("*.py")}
+                    if source_files and target_files and source_files.issubset(target_files):
+                        # Assume already copied if structure matches
+                        return
+
+        try:
+            if source.is_file():
+                shutil.copy2(source, target)
+                self.copied_files.append(target)
+                print(f"Copied external file: {source} -> {target}")
+            elif source.is_dir():
+                if target.exists():
+                    shutil.rmtree(target)
+                shutil.copytree(source, target)
+                self.copied_dirs.append(target)
+                print(f"Copied external directory: {source} -> {target}")
+        except Exception as e:
+            print(f"Error copying {source} to {target}: {e}", file=sys.stderr)
+
+    def _report_ambiguous_imports(self, python_files: list[Path]) -> None:
+        """
+        Report any ambiguous imports that couldn't be resolved.
+
+        Prints warnings to stderr for imports that couldn't be classified
+        as stdlib, third-party, local, or external.
+
+        Args:
+            python_files: List of Python files to check for ambiguous imports
+        """
+        analyzer = ImportAnalyzer(self.project_root)
+        ambiguous: list[ImportInfo] = []
+
+        for file_path in python_files:
+            imports = analyzer.extract_imports(file_path)
+            for imp in imports:
+                analyzer.classify_import(imp, self.src_dir)
+                if imp.classification == "ambiguous":
+                    ambiguous.append(imp)
+
+        if ambiguous:
+            print("\nWarning: Found ambiguous imports that could not be resolved:", file=sys.stderr)
+            for imp in ambiguous:
+                print(
+                    f"  {imp.module_name} (line {imp.line_number} in {imp.file_path})",
+                    file=sys.stderr,
+                )
+
+    def cleanup(self) -> None:
+        """
+        Remove all copied files and directories.
+
+        This method removes all files and directories that were copied
+        during prepare_build(). It handles errors gracefully and clears
+        the internal tracking lists.
+        """
+        # Remove copied directories first (they may contain files)
+        for dir_path in reversed(self.copied_dirs):
+            if dir_path.exists():
+                try:
+                    shutil.rmtree(dir_path)
+                    print(f"Removed copied directory: {dir_path}")
+                except Exception as e:
+                    print(f"Error removing {dir_path}: {e}", file=sys.stderr)
+
+        # Remove copied files
+        for file_path in self.copied_files:
+            if file_path.exists():
+                try:
+                    file_path.unlink()
+                    print(f"Removed copied file: {file_path}")
+                except Exception as e:
+                    print(f"Error removing {file_path}: {e}", file=sys.stderr)
+
+        self.copied_files.clear()
+        self.copied_dirs.clear()
+
+    def run_build(self, build_command: Callable[[], None]) -> None:
+        """
+        Run the build process with dependency management.
+
+        This is a convenience method that:
+        1. Calls prepare_build() to find and copy dependencies
+        2. Executes the provided build_command
+        3. Always calls cleanup() afterward, even if build fails
+
+        Args:
+            build_command: Callable that executes the build process
+
+        Example:
+            ```python
+            def build():
+                subprocess.run(["uv", "build"], check=True)
+
+            manager.run_build(build)
+            ```
+        """
+        try:
+            print("Analyzing project for external dependencies...")
+            external_deps = self.prepare_build()
+
+            if external_deps:
+                print(f"\nFound {len(external_deps)} external dependencies")
+                print("Copied external dependencies into source directory\n")
+            else:
+                print("No external dependencies found\n")
+
+            print("Running build...")
+            build_command()
+
+        finally:
+            print("\nCleaning up copied files...")
+            self.cleanup()
+
+    def build_and_publish(
+        self,
+        build_command: Callable[[], None],
+        repository: str | None = None,
+        repository_url: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        skip_existing: bool = False,
+        version: str | None = None,
+        restore_versioning: bool = True,
+    ) -> None:
+        """
+        Build and publish the package in one operation.
+
+        This method combines build and publish operations:
+        1. Sets version if specified
+        2. Prepares external dependencies
+        3. Runs the build command
+        4. Publishes to the specified repository
+        5. Cleans up copied files
+        6. Restores versioning configuration if requested
+
+        Args:
+            build_command: Callable that executes the build process
+            repository: Target repository ('pypi', 'testpypi', or 'azure')
+            repository_url: Custom repository URL (required for Azure)
+            username: Username for publishing (will prompt if not provided)
+            password: Password/token for publishing (will prompt if not provided)
+            skip_existing: If True, skip files that already exist on the repository
+            version: Manual version to set before building (PEP 440 format)
+            restore_versioning: If True, restore dynamic versioning after build
+
+        Example:
+            ```python
+            def build():
+                subprocess.run(["uv", "build"], check=True)
+
+            manager.build_and_publish(build, repository="pypi", version="1.2.3")
+            ```
+        """
+        from .publisher import Publisher, Repository
+        from .version import VersionManager
+
+        version_manager = None
+        original_version = None
+
+        try:
+            # Set version if specified
+            if version:
+                version_manager = VersionManager(self.project_root)
+                original_version = version_manager.get_current_version()
+                print(f"Setting version to {version}...")
+                version_manager.set_version(version)
+
+            # Build the package
+            self.run_build(build_command)
+
+            # Publish if repository is specified
+            if repository:
+                publisher = Publisher(
+                    repository=repository,
+                    dist_dir=self.project_root / "dist",
+                    repository_url=repository_url,
+                    username=username,
+                    password=password,
+                )
+                publisher.publish(skip_existing=skip_existing)
+        finally:
+            # Restore versioning if needed
+            if version_manager and restore_versioning:
+                try:
+                    if original_version:
+                        version_manager.set_version(original_version)
+                    else:
+                        version_manager.restore_dynamic_versioning()
+                    print("Restored versioning configuration")
+                except Exception as e:
+                    print(f"Warning: Could not restore versioning: {e}", file=sys.stderr)
+
+            # Cleanup is already handled by run_build, but ensure it's done
+            if self.copied_files or self.copied_dirs:
+                self.cleanup()

python_package_folder/publisher.py

@@ -0,0 +1,246 @@
+"""
+Package publishing functionality.
+
+This module provides functionality to publish built packages to various
+repositories including PyPI, PyPI Test, and Azure Artifacts.
+"""
+
+from __future__ import annotations
+
+import getpass
+import subprocess
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Literal
+
+try:
+    import keyring
+except ImportError:
+    keyring = None
+
+
+class Repository(Enum):
+    """
+    Supported package repositories.
+
+    Attributes:
+        PYPI: Official Python Package Index (https://pypi.org)
+        PYPI_TEST: Test PyPI for testing package uploads (https://test.pypi.org)
+        AZURE: Azure Artifacts feed (requires custom repository_url)
+    """
+
+    PYPI = "pypi"
+    PYPI_TEST = "testpypi"
+    AZURE = "azure"
+
+
+class Publisher:
+    """
+    Handles publishing Python packages to various repositories.
+
+    This class manages the publishing process, including credential handling
+    and repository configuration. It uses twine under the hood for actual publishing.
+
+    Attributes:
+        repository: Target repository for publishing
+        dist_dir: Directory containing built distribution files
+        repository_url: Custom repository URL (for Azure or custom PyPI servers)
+        username: Username for authentication (optional, can be prompted)
+        password: Password/token for authentication (optional, can be prompted)
+    """
+
+    def __init__(
+        self,
+        repository: Repository | str,
+        dist_dir: Path | None = None,
+        repository_url: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+    ) -> None:
+        """
+        Initialize the publisher.
+
+        Args:
+            repository: Target repository (Repository enum or string)
+            dist_dir: Directory containing distribution files (default: dist/)
+            repository_url: Custom repository URL (required for Azure)
+            username: Username for authentication (will prompt if not provided)
+            password: Password/token for authentication (will prompt if not provided)
+        """
+        if isinstance(repository, str):
+            try:
+                self.repository = Repository(repository.lower())
+            except ValueError:
+                valid_repos = ", ".join(r.value for r in Repository)
+                raise ValueError(f"Invalid repository: {repository}. Must be one of: {valid_repos}")
+        else:
+            self.repository = repository
+
+        self.dist_dir = dist_dir or Path("dist")
+        self.repository_url = repository_url
+        self.username = username
+        self.password = password
+
+    def _get_repository_url(self) -> str:
+        """Get the repository URL based on the selected repository."""
+        if self.repository_url:
+            return self.repository_url
+
+        if self.repository == Repository.PYPI:
+            return "https://upload.pypi.org/legacy/"
+        elif self.repository == Repository.PYPI_TEST:
+            return "https://test.pypi.org/legacy/"
+        elif self.repository == Repository.AZURE:
+            if not self.repository_url:
+                raise ValueError("repository_url is required for Azure Artifacts")
+            return self.repository_url
+
+        raise ValueError(f"Unknown repository: {self.repository}")
+
+    def _get_credentials(self) -> tuple[str, str]:
+        """
+        Get credentials for publishing.
+
+        Prompts for username and password/token if not already provided.
+        Uses keyring if available to store/retrieve credentials securely.
+
+        Returns:
+            Tuple of (username, password/token)
+        """
+        username = self.username
+        password = self.password
+
+        # Try to get from keyring if available
+        if keyring and not username:
+            try:
+                username = keyring.get_password(f"python-package-folder-{self.repository.value}", "username")
+            except Exception:
+                pass
+
+        if keyring and not password:
+            try:
+                password = keyring.get_password(f"python-package-folder-{self.repository.value}", username or "token")
+            except Exception:
+                pass
+
+        # Prompt if still not available
+        if not username:
+            username = input(f"Enter username for {self.repository.value}: ").strip()
+            if not username:
+                raise ValueError("Username is required")
+
+        if not password:
+            if self.repository == Repository.AZURE:
+                prompt = f"Enter Azure Artifacts token for {username}: "
+            else:
+                prompt = f"Enter PyPI token for {username} (or __token__ for API token): "
+            password = getpass.getpass(prompt)
+            if not password:
+                raise ValueError("Password/token is required")
+
+        # Store in keyring if available
+        if keyring:
+            try:
+                keyring.set_password(f"python-package-folder-{self.repository.value}", "username", username)
+                keyring.set_password(f"python-package-folder-{self.repository.value}", username, password)
+            except Exception:
+                # Keyring storage is optional, continue if it fails
+                pass
+
+        return username, password
+
+    def _check_twine_installed(self) -> bool:
+        """Check if twine is installed."""
+        try:
+            subprocess.run(["twine", "--version"], capture_output=True, check=True)
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return False
+
+    def publish(self, skip_existing: bool = False) -> None:
+        """
+        Publish the package to the selected repository.
+
+        Args:
+            skip_existing: If True, skip files that already exist on the repository
+
+        Raises:
+            ValueError: If twine is not installed or credentials are invalid
+            subprocess.CalledProcessError: If publishing fails
+        """
+        if not self._check_twine_installed():
+            raise ValueError(
+                "twine is required for publishing. Install it with: pip install twine"
+            )
+
+        if not self.dist_dir.exists():
+            raise ValueError(f"Distribution directory not found: {self.dist_dir}")
+
+        dist_files = list(self.dist_dir.glob("*.whl")) + list(self.dist_dir.glob("*.tar.gz"))
+        if not dist_files:
+            raise ValueError(f"No distribution files found in {self.dist_dir}")
+
+        username, password = self._get_credentials()
+        repo_url = self._get_repository_url()
+
+        # Build twine command
+        cmd = ["twine", "upload"]
+        if skip_existing:
+            cmd.append("--skip-existing")
+        cmd.extend(["--repository-url", repo_url])
+        cmd.extend(["--username", username])
+        cmd.extend(["--password", password])
+        cmd.extend([str(f) for f in dist_files])
+
+        print(f"\nPublishing to {self.repository.value} at {repo_url}")
+        print(f"Files to upload: {len(dist_files)}")
+
+        try:
+            result = subprocess.run(cmd, check=True, text=True)
+            print(f"\n✓ Successfully published to {self.repository.value}")
+        except subprocess.CalledProcessError as e:
+            print(f"\n✗ Failed to publish to {self.repository.value}", file=sys.stderr)
+            print(f"Error: {e}", file=sys.stderr)
+            raise
+
+    def publish_interactive(self, skip_existing: bool = False) -> None:
+        """
+        Publish with interactive credential prompts.
+
+        This is a convenience method that ensures credentials are prompted
+        even if they were provided during initialization.
+
+        Args:
+            skip_existing: If True, skip files that already exist on the repository
+        """
+        # Clear cached credentials to force prompt
+        self.username = None
+        self.password = None
+        self.publish(skip_existing=skip_existing)
+
+
+def get_repository_help() -> str:
+    """
+    Get help text for repository configuration.
+
+    Returns:
+        Helpful text about repository options and configuration
+    """
+    return """
+Repository Options:
+  - pypi: Official Python Package Index (https://pypi.org)
+  - testpypi: Test PyPI for testing package uploads (https://test.pypi.org)
+  - azure: Azure Artifacts feed (requires repository_url)
+
+For PyPI/TestPyPI:
+  - Username: Your PyPI username or '__token__' for API tokens
+  - Password: Your PyPI password or API token
+
+For Azure Artifacts:
+  - Username: Your Azure username or feed name
+  - Password: Personal Access Token (PAT) with packaging permissions
+  - Repository URL: Your Azure Artifacts feed URL
+    Example: https://pkgs.dev.azure.com/ORG/PROJECT/_packaging/FEED/pypi/upload
+"""
+