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

python_package_folder/__init__.py

@@ -0,0 +1,24 @@
+"""Python package folder - Build Python packages with external dependency management."""
+
+__all__ = (
+    "BuildManager",
+    "ExternalDependency",
+    "ExternalDependencyFinder",
+    "ImportAnalyzer",
+    "ImportInfo",
+    "Publisher",
+    "Repository",
+    "SubfolderBuildConfig",
+    "VersionManager",
+    "find_project_root",
+    "find_source_directory",
+)
+
+from .analyzer import ImportAnalyzer
+from .finder import ExternalDependencyFinder
+from .manager import BuildManager
+from .publisher import Publisher, Repository
+from .subfolder_build import SubfolderBuildConfig
+from .types import ExternalDependency, ImportInfo
+from .utils import find_project_root, find_source_directory
+from .version import VersionManager

python_package_folder/__main__.py

@@ -0,0 +1,13 @@
+"""
+Allow running the package as a module.
+
+This module enables running the package with:
+    python -m python_package_folder
+
+It simply delegates to the main() function from python_package_folder.py.
+"""
+
+from .python_package_folder import main
+
+if __name__ == "__main__":
+    exit(main())

python_package_folder/analyzer.py

@@ -0,0 +1,313 @@
+"""
+Import analysis functionality.
+
+This module provides the ImportAnalyzer class which is responsible for:
+- Finding all Python files in a directory tree
+- Extracting import statements using AST parsing
+- Classifying imports as stdlib, third-party, local, external, or ambiguous
+- Resolving import paths to actual file locations
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import sys
+from pathlib import Path
+
+from .types import ImportInfo
+
+
+class ImportAnalyzer:
+    """
+    Analyzes Python files to extract and classify import statements.
+
+    This class uses Python's AST module to parse Python files and extract
+    all import statements. It can classify imports into different categories
+    and resolve their file paths.
+
+    Attributes:
+        project_root: Root directory of the project
+        _stdlib_modules: Cached set of standard library module names
+    """
+
+    def __init__(self, project_root: Path) -> None:
+        """
+        Initialize the import analyzer.
+
+        Args:
+            project_root: Root directory of the project to analyze
+        """
+        self.project_root = project_root.resolve()
+        self._stdlib_modules: set[str] | None = None
+
+    def find_all_python_files(self, directory: Path) -> list[Path]:
+        """
+        Recursively find all Python files in a directory.
+
+        Args:
+            directory: Directory to search for Python files
+
+        Returns:
+            List of paths to all .py files found in the directory tree
+        """
+        return [path for path in directory.rglob("*.py") if path.is_file()]
+
+    def extract_imports(self, file_path: Path) -> list[ImportInfo]:
+        """
+        Extract all import statements from a Python file.
+
+        Uses AST parsing to find both `import` and `from ... import` statements.
+        Handles syntax errors gracefully by returning an empty list.
+
+        Args:
+            file_path: Path to the Python file to analyze
+
+        Returns:
+            List of ImportInfo objects representing all imports found in the file
+        """
+        imports: list[ImportInfo] = []
+
+        try:
+            content = file_path.read_text(encoding="utf-8")
+            tree = ast.parse(content, filename=str(file_path))
+        except (SyntaxError, UnicodeDecodeError) as e:
+            print(f"Warning: Could not parse {file_path}: {e}", file=sys.stderr)
+            return imports
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.append(
+                        ImportInfo(
+                            module_name=alias.name,
+                            import_type="import",
+                            line_number=node.lineno,
+                            file_path=file_path,
+                        )
+                    )
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    imports.append(
+                        ImportInfo(
+                            module_name=node.module,
+                            import_type="from",
+                            from_module=node.module,
+                            line_number=node.lineno,
+                            file_path=file_path,
+                        )
+                    )
+
+        return imports
+
+    def get_stdlib_modules(self) -> set[str]:
+        """
+        Get a set of standard library module names.
+
+        Caches the result for performance. Attempts to discover stdlib modules
+        by examining the Python installation directory, with a fallback list
+        of common standard library modules.
+
+        Returns:
+            Set of standard library module names
+        """
+        if self._stdlib_modules is not None:
+            return self._stdlib_modules
+
+        stdlib_modules: set[str] = set()
+
+        # Get standard library path
+        stdlib_path = (
+            Path(sys.executable).parent
+            / "lib"
+            / f"python{sys.version_info.major}.{sys.version_info.minor}"
+        )
+        if not stdlib_path.exists():
+            # Fallback: try to import and check sys.path
+            import sysconfig
+
+            stdlib_path = Path(sysconfig.get_path("stdlib"))
+
+        if stdlib_path.exists():
+            for item in stdlib_path.iterdir():
+                if item.is_file() and item.suffix == ".py":
+                    stdlib_modules.add(item.stem)
+                elif (
+                    item.is_dir()
+                    and not item.name.startswith("_")
+                    and (item / "__init__.py").exists()
+                ):
+                    stdlib_modules.add(item.name)
+
+        # Add common stdlib modules that might not be in the directory
+        common_stdlib = {
+            "sys",
+            "os",
+            "json",
+            "pathlib",
+            "typing",
+            "collections",
+            "itertools",
+            "functools",
+            "dataclasses",
+            "enum",
+            "abc",
+            "contextlib",
+            "io",
+            "textwrap",
+            "ast",
+            "importlib",
+            "shutil",
+            "subprocess",
+        }
+        stdlib_modules.update(common_stdlib)
+
+        self._stdlib_modules = stdlib_modules
+        return stdlib_modules
+
+    def classify_import(self, import_info: ImportInfo, src_dir: Path) -> None:
+        """
+        Classify an import as stdlib, third-party, local, external, or ambiguous.
+
+        Modifies the ImportInfo object in place, setting its classification
+        and resolved_path attributes.
+
+        Args:
+            import_info: ImportInfo object to classify
+            src_dir: Source directory to use for determining local vs external
+        """
+        module_name = import_info.module_name
+        stdlib_modules = self.get_stdlib_modules()
+
+        # Check if it's a standard library module
+        root_module = module_name.split(".")[0]
+        if root_module in stdlib_modules:
+            import_info.classification = "stdlib"
+            return
+
+        # Try to resolve as a local import
+        resolved = self.resolve_local_import(import_info, src_dir)
+        if resolved is not None:
+            if resolved.is_relative_to(src_dir):
+                import_info.classification = "local"
+            else:
+                import_info.classification = "external"
+            import_info.resolved_path = resolved
+            return
+
+        # Check if it's a third-party package (in site-packages)
+        if self.is_third_party(module_name):
+            import_info.classification = "third_party"
+            return
+
+        # Mark as ambiguous if we can't determine
+        import_info.classification = "ambiguous"
+
+    def resolve_local_import(self, import_info: ImportInfo, src_dir: Path) -> Path | None:
+        """
+        Try to resolve a local import to a file path.
+
+        Handles both relative imports (starting with .) and absolute imports.
+        Checks multiple potential locations including parent directories
+        of the source directory.
+
+        Args:
+            import_info: ImportInfo object with the import to resolve
+            src_dir: Source directory to use as reference
+
+        Returns:
+            Path to the resolved file, or None if not found
+        """
+        module_name = import_info.module_name
+
+        # Handle relative imports
+        if import_info.file_path:
+            file_dir = import_info.file_path.parent
+            if module_name.startswith("."):
+                # Relative import
+                parts = module_name.split(".")
+                level = sum(1 for p in parts if p == "")
+                module_parts = [p for p in parts if p]
+
+                if level > 0:
+                    # Go up 'level' directories
+                    current = file_dir
+                    for _ in range(level - 1):
+                        current = current.parent
+                    base_path = current
+                else:
+                    base_path = file_dir
+
+                if module_parts:
+                    potential_path = base_path / "/".join(module_parts)
+                else:
+                    potential_path = base_path
+
+                # Try as module
+                if (potential_path / "__init__.py").exists():
+                    return potential_path / "__init__.py"
+                if potential_path.with_suffix(".py").exists():
+                    return potential_path.with_suffix(".py")
+                if potential_path.is_dir() and (potential_path / "__init__.py").exists():
+                    return potential_path / "__init__.py"
+
+        # Handle absolute imports - check if it's in the project
+        # First check if it's in src_dir
+        module_path_str = module_name.replace(".", "/")
+        potential_paths = [
+            src_dir / module_path_str / "__init__.py",
+            (src_dir / module_path_str).with_suffix(".py"),
+            self.project_root / module_path_str / "__init__.py",
+            (self.project_root / module_path_str).with_suffix(".py"),
+        ]
+
+        for path in potential_paths:
+            if path.exists():
+                return path
+
+        # Check parent directories of src_dir and project_root for external dependencies
+        # Check up to project_root's parent
+        check_dirs = [src_dir.parent] + list(src_dir.parents)
+        for parent in check_dirs:
+            if parent == self.project_root.parent:
+                break
+            if not parent.exists():
+                continue
+
+            # Try as module directory
+            potential = parent / module_name.replace(".", "/")
+            if potential.is_dir() and (potential / "__init__.py").exists():
+                return potential / "__init__.py"
+            if potential.with_suffix(".py").is_file():
+                return potential.with_suffix(".py")
+
+            # Also check if the parent itself contains the module
+            potential_file = parent / f"{module_name.split('.')[-1]}.py"
+            if potential_file.exists():
+                return potential_file
+
+        return None
+
+    def is_third_party(self, module_name: str) -> bool:
+        """
+        Check if a module is a third-party package.
+
+        Uses importlib to find the module and checks if its location
+        is in site-packages or dist-packages.
+
+        Args:
+            module_name: Name of the module to check
+
+        Returns:
+            True if the module is a third-party package, False otherwise
+        """
+        root_module = module_name.split(".")[0]
+        try:
+            spec = importlib.util.find_spec(root_module)
+            if spec and spec.origin:
+                origin_path = Path(spec.origin)
+                # Check if it's in site-packages
+                return "site-packages" in str(origin_path) or "dist-packages" in str(origin_path)
+        except (ImportError, ValueError, AttributeError):
+            pass
+        return False

python_package_folder/finder.py

@@ -0,0 +1,234 @@
+"""
+External dependency finding functionality.
+
+This module provides the ExternalDependencyFinder class which identifies
+files and directories that are imported from outside the source directory
+and need to be temporarily copied during the build process.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .analyzer import ImportAnalyzer
+from .types import ExternalDependency
+
+
+class ExternalDependencyFinder:
+    """
+    Finds external dependencies that need to be copied.
+
+    This class analyzes Python files to identify imports that reference
+    modules outside the source directory. It determines which files or
+    directories need to be copied and where they should be placed.
+
+    Attributes:
+        project_root: Root directory of the project
+        src_dir: Source directory where the package code lives
+        analyzer: ImportAnalyzer instance for analyzing imports
+    """
+
+    def __init__(
+        self, project_root: Path, src_dir: Path, exclude_patterns: list[str] | None = None
+    ) -> None:
+        """
+        Initialize the dependency finder.
+
+        Args:
+            project_root: Root directory of the project
+            src_dir: Source directory to analyze
+            exclude_patterns: Additional patterns to exclude (default: common sandbox patterns)
+        """
+        self.project_root = project_root.resolve()
+        self.src_dir = src_dir.resolve()
+        self.analyzer = ImportAnalyzer(project_root)
+        # Patterns for directories/files to exclude (sandbox, skip, etc.)
+        default_patterns = [
+            "_SS",
+            "__SS",
+            "_sandbox",
+            "__sandbox",
+            "_skip",
+            "__skip",
+            "_test",
+            "__test__",
+        ]
+        self.exclude_patterns = default_patterns + (exclude_patterns or [])
+
+    def find_external_dependencies(self, python_files: list[Path]) -> list[ExternalDependency]:
+        """
+        Find all external dependencies that need to be copied.
+
+        Analyzes all provided Python files, classifies their imports,
+        and identifies which external files/directories need to be copied
+        into the source directory.
+
+        Args:
+            python_files: List of Python file paths to analyze
+
+        Returns:
+            List of ExternalDependency objects representing files/directories
+            that need to be copied
+        """
+        external_deps: list[ExternalDependency] = []
+        seen_paths: set[Path] = set()
+
+        for file_path in python_files:
+            imports = self.analyzer.extract_imports(file_path)
+            for imp in imports:
+                self.analyzer.classify_import(imp, self.src_dir)
+
+                if imp.classification == "external" and imp.resolved_path:
+                    source_path = imp.resolved_path
+
+                    # Skip excluded paths (sandbox directories, etc.)
+                    if self._should_exclude_path(source_path):
+                        continue
+
+                    # For files, only copy parent directory if it's a package
+                    # Otherwise, copy just the individual file
+                    if source_path.is_file():
+                        parent_dir = source_path.parent
+
+                        # Only copy parent directory if:
+                        # 1. It's a package (has __init__.py), OR
+                        # 2. Files from it are actually imported (which is the case here)
+                        # But only copy the immediate parent, not entire directory trees
+                        parent_is_package = (parent_dir / "__init__.py").exists()
+                        files_are_imported = True  # Always true when processing an import
+
+                        # Only copy immediate parent directory, not grandparent directories
+                        # This prevents copying entire trees like models/Information_extraction
+                        # when we only need models/Information_extraction/_shared_ie
+                        should_copy_dir = (
+                            not self._should_exclude_path(parent_dir)
+                            and (
+                                parent_is_package or files_are_imported
+                            )  # Package OR files imported
+                            and not parent_dir.is_relative_to(self.src_dir)
+                            and not self.src_dir.is_relative_to(parent_dir)
+                            and parent_dir != self.project_root
+                            and parent_dir != self.project_root.parent
+                        )
+
+                        if should_copy_dir:
+                            # Copy the directory instead of just the file
+                            track_path = parent_dir
+                            source_path = parent_dir
+                        else:
+                            # Copy just the file
+                            track_path = source_path
+                    elif source_path.is_dir():
+                        # Don't copy directories that contain src_dir
+                        if self.src_dir.is_relative_to(source_path):
+                            continue
+                        track_path = source_path
+                    else:
+                        continue
+
+                    if track_path in seen_paths:
+                        continue
+                    seen_paths.add(track_path)
+
+                    # Determine target path within src_dir
+                    target_path = self._determine_target_path(source_path, imp.module_name)
+
+                    if target_path:
+                        # Only add if source is actually outside src_dir
+                        if not source_path.is_relative_to(self.src_dir):
+                            external_deps.append(
+                                ExternalDependency(
+                                    source_path=source_path,
+                                    target_path=target_path,
+                                    import_name=imp.module_name,
+                                    file_path=file_path,
+                                )
+                            )
+
+        return external_deps
+
+    def _determine_target_path(self, source_path: Path, module_name: str) -> Path | None:
+        """
+        Determine where an external file should be copied within src_dir.
+
+        For files, attempts to maintain the module structure. For directories,
+        places them directly in src_dir with their original name.
+
+        Args:
+            source_path: Path to the source file or directory
+            module_name: Module name from the import statement
+
+        Returns:
+            Target path within src_dir, or None if cannot be determined
+        """
+        if not source_path.exists():
+            return None
+
+        # Always create target within src_dir
+        module_parts = module_name.split(".")
+
+        if source_path.is_file():
+            # For a file, create the directory structure based on module name
+            if len(module_parts) > 1:
+                # It's a submodule, create the directory structure
+                target = self.src_dir / "/".join(module_parts[:-1]) / source_path.name
+            else:
+                # Top-level module - try to find the main package directory
+                # or create a matching structure
+                main_pkg = self._find_main_package()
+                if main_pkg:
+                    target = main_pkg / source_path.name
+                else:
+                    target = self.src_dir / source_path.name
+            return target
+
+        # If it's a directory, copy the whole directory
+        if source_path.is_dir():
+            # Use the directory name directly in src_dir
+            target = self.src_dir / source_path.name
+            return target
+
+        return None
+
+    def _should_exclude_path(self, path: Path) -> bool:
+        """
+        Check if a path should be excluded from copying.
+
+        Excludes paths that match common sandbox/skip patterns like _SS, __SS, etc.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            True if the path should be excluded, False otherwise
+        """
+        # Check each component of the path
+        for part in path.parts:
+            for pattern in self.exclude_patterns:
+                # Match if part equals pattern or starts with pattern
+                if part == pattern or part.startswith(pattern):
+                    return True
+        return False
+
+    def _find_main_package(self) -> Path | None:
+        """
+        Find the main package directory within src_dir.
+
+        Looks for directories containing __init__.py files, which indicate
+        Python packages.
+
+        Returns:
+            Path to the main package directory, or None 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 package_dirs:
+            return package_dirs[0]
+
+        return None