Enhance subfolder build process with version mismatch detection and pyproject.toml handling

This commit introduces a new section in the documentation detailing version mismatch detection during the publishing process. It updates the version in the subfolder's `pyproject.toml` to match the derived version, providing warnings for discrepancies. Additionally, the handling of subfolder `pyproject.toml` is improved, including automatic merging of fields, dependency management, and exclusion patterns. The BuildManager and Publisher classes are updated to support these enhancements, ensuring a more robust build process for subfolder packages.

Author: alelom

docs/PUBLISHING.md

@@ -51,6 +51,17 @@ When publishing, the tool automatically filters distribution files to only uploa
 
 This ensures that when building a subfolder package, only that package's distribution files are uploaded, not files from previous builds of other packages.
 
+## Version Mismatch Detection
+
+If there's a version mismatch between the built package and the expected version (e.g., when a subfolder's `pyproject.toml` has a different version than the derived version), the error message will show:
+
+- What version was actually built
+- What version is expected for publishing
+- An explanation of the mismatch
+- A solution suggestion
+
+The tool automatically updates the version in the subfolder's `pyproject.toml` to match the derived version, so this error should only occur if the build process fails before the version update takes effect.
+
 To get a PyPI API token:
 1. Go to https://pypi.org/manage/account/token/
 2. Create a new API token

docs/USAGE.md

@@ -75,7 +75,13 @@ The tool automatically:
 - Uses the current directory as the source directory if it contains Python files
 - Falls back to `project_root/src` if the current directory isn't suitable
 - **For subfolder builds**: Handles `pyproject.toml` configuration:
-  - **If `pyproject.toml` exists in subfolder**: Uses that file (copies it to project root temporarily, adjusting package paths and ensuring `[build-system]` uses hatchling)
+  - **If `pyproject.toml` exists in subfolder**: 
+    - Uses that file (copies it to project root temporarily, adjusting package paths and ensuring `[build-system]` uses hatchling)
+    - **Version handling**: The version in the subfolder's `pyproject.toml` is automatically updated to match the derived version (from conventional commits or `--version` argument). A warning is shown if versions differ.
+    - **Name handling**: If the subfolder's `pyproject.toml` has a `name` field that differs from the derived name, a warning is shown but the subfolder's name is used (not the derived one).
+    - **Dependencies handling**: If the subfolder's `pyproject.toml` has a non-empty `dependencies` field, automatic dependency detection is skipped with a warning. To enable automatic detection, remove or empty the `dependencies` field.
+    - **Field merging**: Missing fields (like `description`, `authors`, `keywords`, `classifiers`, `license`, `urls`, etc.) are automatically filled from the parent `pyproject.toml` if available.
+    - **Exclude patterns**: Exclude patterns from the parent `pyproject.toml` are merged into the subfolder's configuration.
   - **If no `pyproject.toml` in subfolder**: Creates a temporary `pyproject.toml` with:
     - `[build-system]` section using hatchling (always uses hatchling, even if parent uses setuptools)
     - Package name derived from the subfolder name (e.g., `empty_drawing_detection` → `empty-drawing-detection`)
@@ -101,11 +107,32 @@ python-package-folder --version "0.1.0" --package-name "my-subfolder-package" --
 python-package-folder --version "0.1.0" --dependency-group "dev" --publish pypi
 
 # If subfolder has its own pyproject.toml, it will be used automatically
-# (package-name and version arguments are ignored in this case)
+# The version will be updated to match the derived version (from conventional commits)
+# The package name from the subfolder toml will be used (even if it differs from derived)
 cd src/integration/my_package  # assuming my_package/pyproject.toml exists
 python-package-folder --publish pypi
 ```
 
+**Subfolder `pyproject.toml` Behavior:**
+
+When a subfolder has its own `pyproject.toml`, the tool intelligently merges it with derived information:
+
+1. **Version**: Always updated to match the derived version (from conventional commits or `--version`). If the subfolder's version differs, a warning is shown but the derived version is used.
+
+2. **Name**: If the subfolder's `pyproject.toml` has a `name` field, it takes precedence over the derived name. A warning is shown if they differ.
+
+3. **Dependencies**: 
+   - If the subfolder's `pyproject.toml` has a non-empty `dependencies` field, automatic dependency detection is **skipped** (with a warning).
+   - To enable automatic dependency detection, remove or empty the `dependencies` field in the subfolder's `pyproject.toml`.
+   - If the `dependencies` field is empty or missing, automatic detection proceeds normally.
+
+4. **Field Merging**: Missing fields are automatically filled from the parent `pyproject.toml`:
+   - `description`, `readme`, `requires-python`, `authors`, `keywords`, `classifiers`, `license`
+   - `[project.urls]` section
+   - Other `[tool.*]` sections (except `tool.hatch.build.*` and `tool.python-package-folder.*`)
+
+5. **Exclude Patterns**: Automatically merged from parent `pyproject.toml`.
+
 **Dependency Groups**: When building a subfolder, you can specify a dependency group from the parent `pyproject.toml` to include in the subfolder's build configuration. This allows subfolders to inherit specific dependencies from the parent project:
 
 ```bash

src/python_package_folder/manager.py

@@ -255,28 +255,46 @@ def prepare_build(
                     # Fallback to just subfolder name if root project name not found
                     package_name = subfolder_name
 
-            print(
-                f"Detected subfolder build. Setting up package '{package_name}' version '{version}'..."
-            )
-            self.subfolder_config = SubfolderBuildConfig(
-                project_root=self.project_root,
-                src_dir=self.src_dir,
-                package_name=package_name,
-                version=version,
-                dependency_group=dependency_group,
-            )
-            temp_pyproject = self.subfolder_config.create_temp_pyproject()
-            # If temp_pyproject is None, it means no parent pyproject.toml exists
-            # This is acceptable for tests or dependency-only operations
-            if temp_pyproject is None:
-                self.subfolder_config = None
+            # Check if subfolder_config already exists with the same parameters
+            # This makes prepare_build() idempotent - safe to call multiple times
+            if (
+                self.subfolder_config
+                and self.subfolder_config.package_name == package_name
+                and self.subfolder_config.version == version
+                and self.subfolder_config.dependency_group == dependency_group
+                and self.subfolder_config._temp_package_dir
+                and self.subfolder_config._temp_package_dir.exists()
+            ):
+                print(
+                    f"Subfolder config already exists for '{package_name}' version '{version}', reusing it..."
+                )
+                # Still need to find external dependencies, so continue with that
+                # temp_pyproject should already exist from previous call
+                temp_pyproject = self.subfolder_config.temp_pyproject
             else:
+                print(
+                    f"Detected subfolder build. Setting up package '{package_name}' version '{version}'..."
+                )
+                self.subfolder_config = SubfolderBuildConfig(
+                    project_root=self.project_root,
+                    src_dir=self.src_dir,
+                    package_name=package_name,
+                    version=version,
+                    dependency_group=dependency_group,
+                )
+                temp_pyproject = self.subfolder_config.create_temp_pyproject()
+                # If temp_pyproject is None, it means no parent pyproject.toml exists
+                # This is acceptable for tests or dependency-only operations
+                if temp_pyproject is None:
+                    self.subfolder_config = None
+            
+            # If we have a subfolder_config (either newly created or reused), use temp package dir
+            if self.subfolder_config:
                 # If temporary package directory was created, use it for all operations
                 # This ensures dependencies are copied to the correct location and
                 # imports are fixed in the files that will actually be packaged
                 if (
-                    self.subfolder_config
-                    and self.subfolder_config._temp_package_dir
+                    self.subfolder_config._temp_package_dir
                     and self.subfolder_config._temp_package_dir.exists()
                 ):
                     # Update src_dir to point to temp package directory

src/python_package_folder/publisher.py

@@ -9,6 +9,7 @@
 
 import getpass
 import os
+import re
 import subprocess
 import sys
 from enum import Enum
@@ -284,10 +285,40 @@ def publish(self, skip_existing: bool = False) -> None:
 
         if not dist_files:
             if self.package_name and self.version:
-                raise ValueError(
+                # Try to find what version was actually built
+                built_versions = set()
+                for dist_file in all_dist_files:
+                    # Extract version from filename: package-name-version-*.whl
+                    # Pattern: {package_name}-{version}-{...}
+                    if self.package_name.replace("-", "_") in dist_file.name or self.package_name in dist_file.name:
+                        # Try to extract version from filename
+                        parts = dist_file.stem.split("-")
+                        # Look for version-like pattern (e.g., 1.2.3)
+                        for i, part in enumerate(parts):
+                            if re.match(r"^\d+\.\d+\.\d+", part):
+                                built_versions.add(part)
+                                break
+                
+                error_msg = (
                     f"No distribution files found matching package '{self.package_name}' "
-                    f"version '{self.version}' in {self.dist_dir}"
+                    f"version '{self.version}' in {self.dist_dir}\n"
                 )
+                
+                if built_versions:
+                    error_msg += (
+                        f"  - Built package version(s): {', '.join(sorted(built_versions))}\n"
+                        f"  - Expected version for publishing: {self.version}\n"
+                        f"  - This usually indicates a version mismatch between the built package and the expected version.\n"
+                        f"  - Solution: The version in the subfolder's pyproject.toml will be automatically updated to match the derived version."
+                    )
+                else:
+                    error_msg += (
+                        f"  - No distribution files found for package '{self.package_name}' in {self.dist_dir}\n"
+                        f"  - Available files: {[f.name for f in all_dist_files[:5]]}"
+                        + (f" (and {len(all_dist_files) - 5} more)" if len(all_dist_files) > 5 else "")
+                    )
+                
+                raise ValueError(error_msg)
             else:
                 raise ValueError(f"No distribution files found in {self.dist_dir}")