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

python_package_folder/publisher.py

@@ -0,0 +1,310 @@
+"""
+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
+
+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,
+        package_name: str | None = None,
+        version: 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)
+            package_name: Package name to filter distribution files (optional)
+            version: Package version to filter distribution files (optional)
+        """
+        if isinstance(repository, str):
+            try:
+                self.repository = Repository(repository.lower())
+            except ValueError as err:
+                valid_repos = ", ".join(r.value for r in Repository)
+                raise ValueError(
+                    f"Invalid repository: {repository}. Must be one of: {valid_repos}"
+                ) from err
+        else:
+            self.repository = repository
+
+        self.dist_dir = dist_dir or Path("dist")
+        self.repository_url = repository_url
+        self.username = username
+        self.password = password
+        self.package_name = package_name
+        self.version = version
+
+    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")
+
+        # Auto-detect if password is an API token and adjust username
+        if password.startswith("pypi-") or password.startswith("pypi_Ag"):
+            # This is an API token, username should be __token__
+            if username != "__token__":
+                print(
+                    f"Note: Detected API token. Using '__token__' as username instead of '{username}'",
+                    file=sys.stderr,
+                )
+                username = "__token__"
+
+        # 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}")
+
+        all_dist_files = list(self.dist_dir.glob("*.whl")) + list(self.dist_dir.glob("*.tar.gz"))
+
+        # Filter files by package name and version if provided
+        if self.package_name and self.version:
+            # Normalize package name - try both hyphen and underscore variants
+            # Wheel names typically use hyphens, but source dists might use underscores
+            name_hyphen = self.package_name.replace("_", "-").lower()
+            name_underscore = self.package_name.replace("-", "_").lower()
+            name_original = self.package_name.lower()
+
+            # Try all name variants
+            name_variants = {name_hyphen, name_underscore, name_original}
+            version_str = self.version
+
+            dist_files = []
+            for f in all_dist_files:
+                # Get the base filename without extension
+                # For wheels: name-version-tag.whl -> name-version-tag
+                # For source: name-version.tar.gz -> name-version
+                stem = f.stem
+                if f.suffix == ".gz" and stem.endswith(".tar"):
+                    # Handle .tar.gz files
+                    stem = stem[:-4]  # Remove .tar
+
+                # Check if filename starts with any name variant followed by version
+                matches = False
+                for name_variant in name_variants:
+                    # Pattern: {name}-{version} or {name}-{version}-{tag}
+                    if stem.startswith(f"{name_variant}-{version_str}"):
+                        matches = True
+                        break
+
+                if matches:
+                    dist_files.append(f)
+        else:
+            dist_files = all_dist_files
+
+        if not dist_files:
+            if self.package_name and self.version:
+                raise ValueError(
+                    f"No distribution files found matching package '{self.package_name}' "
+                    f"version '{self.version}' in {self.dist_dir}"
+                )
+            else:
+                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:
+            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
+"""

python_package_folder/python_package_folder.py

@@ -0,0 +1,239 @@
+"""
+Main entry point for the python-package-folder package.
+
+This module provides the command-line interface for the package.
+It can be invoked via:
+- The `python-package-folder` command (after installation)
+- `python -m python_package_folder`
+- Direct import and call to main()
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from .manager import BuildManager
+from .utils import find_project_root, find_source_directory
+
+
+def main() -> int:
+    """
+    Main entry point for the build script.
+
+    Parses command-line arguments and runs the build process with
+    external dependency management.
+
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Build Python package with external dependency management"
+    )
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        help="Root directory of the project (auto-detected from pyproject.toml if not specified)",
+    )
+    parser.add_argument(
+        "--src-dir",
+        type=Path,
+        help="Source directory to build (default: auto-detected from current directory or project_root/src)",
+    )
+    parser.add_argument(
+        "--analyze-only",
+        action="store_true",
+        help="Only analyze imports, don't run build",
+    )
+    parser.add_argument(
+        "--build-command",
+        default="uv build",
+        help="Command to run for building (default: 'uv build')",
+    )
+    parser.add_argument(
+        "--publish",
+        choices=["pypi", "testpypi", "azure"],
+        help="Publish to repository after building (pypi, testpypi, or azure)",
+    )
+    parser.add_argument(
+        "--repository-url",
+        help="Custom repository URL (required for Azure Artifacts)",
+    )
+    parser.add_argument(
+        "--username",
+        help="Username for publishing (will prompt if not provided)",
+    )
+    parser.add_argument(
+        "--password",
+        help="Password/token for publishing (will prompt if not provided)",
+    )
+    parser.add_argument(
+        "--skip-existing",
+        action="store_true",
+        help="Skip files that already exist on the repository",
+    )
+    parser.add_argument(
+        "--version",
+        help="Set a specific version before building (PEP 440 format, e.g., '1.2.3'). Required for subfolder builds.",
+    )
+    parser.add_argument(
+        "--package-name",
+        help="Package name for subfolder builds (default: derived from source directory name)",
+    )
+    parser.add_argument(
+        "--dependency-group",
+        dest="dependency_group",
+        help="Dependency group name from parent pyproject.toml to include in subfolder build",
+    )
+    parser.add_argument(
+        "--no-restore-versioning",
+        action="store_true",
+        help="Don't restore dynamic versioning after build (keeps static version)",
+    )
+    parser.add_argument(
+        "--exclude-pattern",
+        action="append",
+        dest="exclude_patterns",
+        help="Additional directory/file patterns to exclude from copying (e.g., '_SS', '__sandbox'). Can be specified multiple times.",
+    )
+
+    args = parser.parse_args()
+
+    try:
+        # Auto-detect project root if not specified
+        if args.project_root:
+            project_root = Path(args.project_root).resolve()
+        else:
+            project_root = find_project_root()
+            if project_root is None:
+                print(
+                    "Error: Could not find project root (pyproject.toml not found).\n"
+                    "Please run from a directory with pyproject.toml or specify --project-root",
+                    file=sys.stderr,
+                )
+                return 1
+            print(f"Auto-detected project root: {project_root}")
+
+        # Determine source directory
+        if args.src_dir:
+            src_dir = Path(args.src_dir).resolve()
+        else:
+            # Auto-detect: use current directory if it has Python files, otherwise use project_root/src
+            src_dir = find_source_directory(project_root)
+            if src_dir:
+                print(f"Auto-detected source directory: {src_dir}")
+            else:
+                src_dir = project_root / "src"
+
+        manager = BuildManager(project_root, src_dir, exclude_patterns=args.exclude_patterns)
+
+        if args.analyze_only:
+            external_deps = manager.prepare_build()
+            print(f"\nFound {len(external_deps)} external dependencies:")
+            for dep in external_deps:
+                print(f"  {dep.import_name}: {dep.source_path} -> {dep.target_path}")
+            manager.cleanup()
+            return 0
+
+        def build_cmd() -> None:
+            # Run build command from project root to ensure pyproject.toml is found
+            result = subprocess.run(
+                args.build_command,
+                shell=True,
+                check=False,
+                cwd=project_root,
+            )
+            if result.returncode != 0:
+                sys.exit(result.returncode)
+
+        # Check if building a subfolder (not the main src/)
+        is_subfolder = not src_dir.is_relative_to(project_root / "src") or (
+            src_dir != project_root / "src" and src_dir != project_root
+        )
+
+        # For subfolder builds, version is required
+        if is_subfolder and not args.version and (not args.analyze_only):
+            print(
+                "Error: --version is required when building from a subfolder.\n"
+                "Subfolders must be built as separate packages with their own version.",
+                file=sys.stderr,
+            )
+            return 1
+
+        if args.publish:
+            manager.build_and_publish(
+                build_cmd,
+                repository=args.publish,
+                repository_url=args.repository_url,
+                username=args.username,
+                password=args.password,
+                skip_existing=args.skip_existing,
+                version=args.version,
+                restore_versioning=not args.no_restore_versioning,
+                package_name=args.package_name,
+                dependency_group=args.dependency_group,
+            )
+        else:
+            # Handle version setting even without publishing
+            if args.version:
+                # Check if subfolder build
+                if is_subfolder:
+                    from .subfolder_build import SubfolderBuildConfig
+
+                    package_name = args.package_name or src_dir.name.replace("_", "-").replace(
+                        " ", "-"
+                    ).lower().strip("-")
+                    subfolder_config = SubfolderBuildConfig(
+                        project_root=project_root,
+                        src_dir=src_dir,
+                        package_name=package_name,
+                        version=args.version,
+                        dependency_group=args.dependency_group,
+                    )
+                    try:
+                        subfolder_config.create_temp_pyproject()
+                        manager.run_build(build_cmd)
+                        if not args.no_restore_versioning:
+                            subfolder_config.restore()
+                            print("Restored original pyproject.toml")
+                    except Exception as e:
+                        print(f"Error managing subfolder build: {e}", file=sys.stderr)
+                        if subfolder_config:
+                            subfolder_config.restore()
+                        raise
+                else:
+                    from .version import VersionManager
+
+                    version_manager = VersionManager(project_root)
+                    original_version = version_manager.get_current_version()
+                    try:
+                        print(f"Setting version to {args.version}...")
+                        version_manager.set_version(args.version)
+                        manager.run_build(build_cmd)
+                        if not args.no_restore_versioning:
+                            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"Error managing version: {e}", file=sys.stderr)
+                        raise
+            else:
+                manager.run_build(build_cmd)
+
+        return 0
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        import traceback
+
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())