python-package-folder 0.1.0__tar.gz → 1.0.0__tar.gz

python_package_folder-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,126 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: CI
+
+on:
+  push:
+    # Use ["main", "master"] for CI only on the default branch.
+    # Use ["**"] for CI on all branches.
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        # Update this as needed:
+        # Common platforms: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        os: ["ubuntu-latest"]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    # Linux only by default. Use ${{ matrix.os }} for other OSes.
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      # Generally following uv docs:
+      # https://docs.astral.sh/uv/guides/integration/github/
+
+      - name: Checkout (official GitHub action)
+        uses: actions/checkout@v4
+        with:
+          # Important for versioning plugins:
+          fetch-depth: 0
+
+      - name: Install uv (official Astral action)
+        uses: astral-sh/setup-uv@v5
+        with:
+          # Update this as needed:
+          version: "0.9.5"
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up Python (using uv)
+        run: uv python install
+
+      # Alternately can use the official Python action:
+      # - name: Set up Python (using actions/setup-python)
+      #   uses: actions/setup-python@v5
+      #   with:
+      #     python-version: ${{ matrix.python-version }}
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run linting
+        run: uv run ruff check .
+
+      - name: Run type checking
+        run: uv run basedpyright src/ || true
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=src/python_package_folder --cov-report=xml --cov-report=term tests/
+
+      - name: Generate coverage badge
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+        run: |
+          python -c "
+          import xml.etree.ElementTree as ET
+          import re
+          
+          # Parse coverage.xml
+          tree = ET.parse('coverage.xml')
+          root = tree.getroot()
+          
+          # Get coverage percentage
+          line_rate = float(root.get('line-rate', 0))
+          coverage_percent = int(line_rate * 100)
+          
+          # Determine color based on coverage
+          if coverage_percent >= 80:
+              color = '44cc11'
+          elif coverage_percent >= 60:
+              color = 'dfb317'
+          elif coverage_percent >= 40:
+              color = 'fe7d37'
+          else:
+              color = 'e05d44'
+          
+          # Generate SVG badge
+          svg = f'''<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"99\" height=\"20\">
+            <linearGradient id=\"b\" x2=\"0\" y2=\"100%\">
+              <stop offset=\"0\" stop-color=\"#bbb\" stop-opacity=\".1\"/>
+              <stop offset=\"1\" stop-opacity=\".1\"/>
+            </linearGradient>
+            <mask id=\"a\">
+              <rect width=\"99\" height=\"20\" rx=\"3\" fill=\"#fff\"/>
+            </mask>
+            <g mask=\"url(#a)\">
+              <path fill=\"#555\" d=\"M0 0h63v20H0z\"/>
+              <path fill=\"#{color}\" d=\"M63 0h36v20H63z\"/>
+              <path fill=\"url(#b)\" d=\"M0 0h99v20H0z\"/>
+            </g>
+            <g fill=\"#fff\" text-anchor=\"middle\" font-family=\"DejaVu Sans,Verdana,Geneva,sans-serif\" font-size=\"11\">
+              <text x=\"31.5\" y=\"15\" fill=\"#010101\" fill-opacity=\".3\">coverage</text>
+              <text x=\"31.5\" y=\"14\">coverage</text>
+              <text x=\"81\" y=\"15\" fill=\"#010101\" fill-opacity=\".3\">{coverage_percent}%</text>
+              <text x=\"81\" y=\"14\">{coverage_percent}%</text>
+            </g>
+          </svg>'''
+          
+          with open('coverage.svg', 'w') as f:
+              f.write(svg)
+          "
+
+      - name: Commit coverage badge
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add coverage.svg || true
+          git diff --staged --quiet || git commit -m "Update coverage badge [skip ci]"
+          git push || true

{python_package_folder-0.1.0 → python_package_folder-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-package-folder
-Version: 0.1.0
+Version: 1.0.0
 Summary: Python package to automatically package and build a folder, fetching all relevant dependencies.
 Project-URL: Repository, https://github.com/alelom/python-package-folder
 Author-email: Alessio Lombardi <work@alelom.com>
@@ -20,6 +20,9 @@ Description-Content-Type: text/markdown
 
 # python-package-folder
 
+[![Tests](https://github.com/alelom/python-package-folder/actions/workflows/ci.yml/badge.svg)](https://github.com/alelom/python-package-folder/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/alelom/python-package-folder/main/coverage.svg)](https://github.com/alelom/python-package-folder)
+
 Python package to automatically analyze, detect, and manage external dependencies when building Python packages. This tool recursively parses all Python files in your project, identifies imports from outside the main package directory, and temporarily copies them into the source directory during the build process.
 
 ## Features
@@ -36,6 +39,10 @@ Python package to automatically analyze, detect, and manage external dependencie
 - **Idempotent Operations**: Safely handles repeated runs without duplicating files
 - **Build Integration**: Seamlessly integrates with build tools like `uv build`, `pip build`, etc.
 - **Warning System**: Reports ambiguous imports that couldn't be resolved
+- **Subfolder Build Support**: Build subfolders as separate packages with automatic project root detection
+- **Smart Publishing**: Only uploads distribution files from the current build, filtering out old artifacts
+- **Auto-Detection**: Automatically finds project root and source directory when run from any subdirectory
+- **Authentication Helpers**: Auto-detects API tokens and uses correct username format
 
 ## Installation
 
@@ -64,16 +71,71 @@ uv add twine
 The simplest way to use this package is via the command-line interface:
 
 ```bash
-# Build with automatic dependency management
+# Build with automatic dependency management (from project root)
 python-package-folder --build-command "uv build"
 
 # Analyze dependencies without building
 python-package-folder --analyze-only
 
+# Build from any subdirectory - auto-detects project root and source directory
+cd tests/folder_structure/subfolder_to_build
+python-package-folder --analyze-only
+
 # Specify custom project root and source directory
 python-package-folder --project-root /path/to/project --src-dir /path/to/src --build-command "pip build"
 ```
 
+### Building from Subdirectories
+
+The tool can automatically detect the project root by searching for `pyproject.toml` in parent directories. This allows you to build subfolders of a main project as separate packages:
+
+```bash
+# From a subdirectory, the tool will:
+# 1. Find pyproject.toml in parent directories (project root)
+# 2. Use current directory as source if it contains Python files
+# 3. Build with dependencies from the parent project
+# 4. Create a temporary build config with subfolder-specific name and version
+
+cd my_project/subfolder_to_build
+python-package-folder --version "1.0.0" --publish pypi
+```
+
+**Important**: When building from a subdirectory, you **must** specify `--version` because subfolders are built as separate packages with their own version.
+
+The tool automatically:
+- Finds the project root by looking for `pyproject.toml` in parent directories
+- 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: creates a temporary `pyproject.toml` with:
+  - Package name derived from the subfolder name (or use `--package-name` to override)
+  - Version from `--version` argument
+  - Proper package path configuration for hatchling
+- Creates temporary `__init__.py` files if needed to make subfolders valid Python packages
+- **README handling for subfolder builds**:
+  - If a README file (README.md, README.rst, README.txt, or README) exists in the subfolder, it will be used instead of the parent README
+  - If no README exists in the subfolder, a minimal README with just the folder name will be created
+- Restores the original `pyproject.toml` after build (unless `--no-restore-versioning` is used)
+- Cleans up temporary `__init__.py` files after build
+
+**Subfolder Build Example:**
+```bash
+# Build a subfolder as a separate package
+cd tests/folder_structure/subfolder_to_build
+python-package-folder --version "0.1.0" --package-name "my-subfolder-package" --publish pypi
+
+# Build with a specific dependency group from parent pyproject.toml
+python-package-folder --version "0.1.0" --dependency-group "dev" --publish pypi
+```
+
+**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
+# Use the 'dev' dependency group from parent pyproject.toml
+python-package-folder --version "1.0.0" --dependency-group "dev" --publish pypi
+```
+
+The specified dependency group will be copied from the parent `pyproject.toml`'s `[dependency-groups]` section into the temporary `pyproject.toml` used for the subfolder build.
+
 ### Python API Usage
 
 You can also use the package programmatically:
@@ -189,6 +251,33 @@ The `--version` option:
 
 **Version Format**: Versions must follow PEP 440 (e.g., `1.2.3`, `1.2.3a1`, `1.2.3.post1`, `1.2.3.dev1`)
 
+### Subfolder Versioning
+
+When building from a subdirectory (not the main `src/` directory), you **must** specify `--version`:
+
+```bash
+# Build a subfolder as a separate package
+cd my_project/subfolder_to_build
+python-package-folder --version "1.0.0" --publish pypi
+
+# With custom package name
+python-package-folder --version "1.0.0" --package-name "my-custom-name" --publish pypi
+```
+
+For subfolder builds:
+- **Version is required**: The tool will error if `--version` is not provided
+- **Package name**: Automatically derived from the subfolder name (e.g., `subfolder_to_build` → `subfolder-to-build`)
+- **Temporary configuration**: Creates a temporary `pyproject.toml` with:
+  - Custom package name (from `--package-name` or derived)
+  - Specified version
+  - Correct package path for hatchling
+  - Dependency group from parent (if `--dependency-group` is specified)
+- **Package initialization**: Automatically creates `__init__.py` if the subfolder doesn't have one (required for hatchling)
+- **README handling**: 
+  - If a README file exists in the subfolder, it will be used instead of the parent README
+  - If no README exists in the subfolder, a minimal README with just the folder name will be created
+- **Auto-restore**: Original `pyproject.toml` is restored after build, and temporary `__init__.py` files are removed
+
 ### Python API for Version Management
 
 ```python
@@ -262,6 +351,21 @@ python-package-folder --publish pypi --skip-existing
 **For PyPI/TestPyPI:**
 - **Username**: Your PyPI username, or `__token__` for API tokens
 - **Password**: Your PyPI password or API token (recommended)
+- **Auto-detection**: If you provide an API token (starts with `pypi-`), the tool will automatically use `__token__` as the username, even if you entered a different username
+
+**Common Authentication Issues:**
+- **403 Forbidden**: Usually means you used your username instead of `__token__` with an API token. The tool now auto-detects this.
+- **TestPyPI vs PyPI**: TestPyPI requires a separate account and token from https://test.pypi.org/manage/account/token/
+
+### Smart File Filtering
+
+When publishing, the tool automatically filters distribution files to only upload those matching the current build:
+
+- **Package name matching**: Only uploads files for the package being built
+- **Version matching**: Only uploads files for the specified version
+- **Automatic cleanup**: Old build artifacts in `dist/` are ignored, preventing accidental uploads
+
+This ensures that when building a subfolder package, only that package's distribution files are uploaded, not files from previous builds of other packages.
 
 To get a PyPI API token:
 1. Go to https://pypi.org/manage/account/token/
@@ -350,7 +454,14 @@ options:
   --username USERNAME   Username for publishing (will prompt if not provided)
   --password PASSWORD   Password/token for publishing (will prompt if not provided)
   --skip-existing       Skip files that already exist on the repository
-  --version VERSION     Set a specific version before building (PEP 440 format)
+  --version VERSION     Set a specific version before building (PEP 440 format).
+                        Required for subfolder builds.
+  --package-name PACKAGE_NAME
+                        Package name for subfolder builds (default: derived from
+                        source directory name)
+  --dependency-group DEPENDENCY_GROUP
+                        Dependency group name from parent pyproject.toml to include
+                        in subfolder build
   --no-restore-versioning
                         Don't restore dynamic versioning after build
 ```
@@ -418,15 +529,19 @@ publisher = Publisher(
     repository=Repository.PYPI,
     dist_dir=Path("dist"),
     username="__token__",
-    password="pypi-xxxxx"
+    password="pypi-xxxxx",
+    package_name="my-package",  # Optional: filter files by package name
+    version="1.2.3"              # Optional: filter files by version
 )
 publisher.publish()
 ```
 
 **Methods:**
-- `publish(skip_existing: bool = False) -> None`: Publish the package
+- `publish(skip_existing: bool = False) -> None`: Publish the package (automatically filters by package_name/version if provided)
 - `publish_interactive(skip_existing: bool = False) -> None`: Publish with interactive credential prompts
 
+**Note**: When `package_name` and `version` are provided, only distribution files matching those parameters are uploaded. This prevents uploading old build artifacts.
+
 ### VersionManager
 
 Manages package version in pyproject.toml.
@@ -452,6 +567,39 @@ version_manager.restore_dynamic_versioning()
 - `get_current_version() -> str | None`: Get current version from pyproject.toml
 - `restore_dynamic_versioning() -> None`: Restore dynamic versioning configuration
 
+### SubfolderBuildConfig
+
+Manages temporary build configuration for subfolder builds.
+
+```python
+from python_package_folder import SubfolderBuildConfig
+from pathlib import Path
+
+config = SubfolderBuildConfig(
+    project_root=Path("."),
+    src_dir=Path("subfolder"),
+    package_name="my-subfolder",
+    version="1.0.0"
+)
+
+# Create temporary pyproject.toml
+config.create_temp_pyproject()
+
+# ... build process ...
+
+# Restore original configuration
+config.restore()
+```
+
+**Methods:**
+- `create_temp_pyproject() -> Path`: Create temporary `pyproject.toml` with subfolder-specific configuration
+- `restore() -> None`: Restore original `pyproject.toml` and clean up temporary files
+
+**Note**: This class automatically creates `__init__.py` files if needed to make subfolders valid Python packages. It also handles README files:
+- If a README exists in the subfolder, it will be used instead of the parent README
+- If no README exists in the subfolder, a minimal README with just the folder name will be created
+- The original parent README is backed up and restored after the build completes
+
 ## How It Works
 
 ### Build Process
@@ -474,13 +622,31 @@ version_manager.restore_dynamic_versioning()
 ### Publishing Process
 
 1. **Build Verification**: Ensures distribution files exist in the `dist/` directory
-2. **Credential Management**: 
+2. **File Filtering**: Automatically filters distribution files to only include those matching the current package name and version (prevents uploading old artifacts)
+3. **Credential Management**: 
    - Prompts for credentials if not provided
    - Uses `keyring` for secure storage (if available)
    - Supports both username/password and API tokens
-3. **Repository Configuration**: Configures the target repository (PyPI, TestPyPI, or Azure)
-4. **Upload**: Uses `twine` to upload distribution files to the repository
-5. **Verification**: Confirms successful upload
+   - Auto-detects API tokens and uses `__token__` as username
+4. **Repository Configuration**: Configures the target repository (PyPI, TestPyPI, or Azure)
+5. **Upload**: Uses `twine` to upload distribution files to the repository
+6. **Verification**: Confirms successful upload
+
+### Subfolder Build Process
+
+1. **Project Root Detection**: Searches parent directories for `pyproject.toml`
+2. **Source Directory Detection**: Uses current directory if it contains Python files, otherwise falls back to `project_root/src`
+3. **Package Initialization**: Creates temporary `__init__.py` if subfolder doesn't have one (required for hatchling)
+4. **README Handling**: 
+   - Checks for README files in the subfolder (README.md, README.rst, README.txt, or README)
+   - If found, copies the subfolder README to project root (backing up the original parent README)
+   - If not found, creates a minimal README with just the folder name
+5. **Configuration Creation**: Creates temporary `pyproject.toml` with:
+   - Subfolder-specific package name (derived or custom)
+   - Specified version
+   - Correct package path for hatchling
+6. **Build Execution**: Runs build command with all dependencies in place
+7. **Cleanup**: Restores original `pyproject.toml` and removes temporary `__init__.py`
 
 ## Requirements
 

{python_package_folder-0.1.0 → python_package_folder-1.0.0}/README.md

@@ -1,5 +1,8 @@
 # python-package-folder
 
+[![Tests](https://github.com/alelom/python-package-folder/actions/workflows/ci.yml/badge.svg)](https://github.com/alelom/python-package-folder/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/alelom/python-package-folder/main/coverage.svg)](https://github.com/alelom/python-package-folder)
+
 Python package to automatically analyze, detect, and manage external dependencies when building Python packages. This tool recursively parses all Python files in your project, identifies imports from outside the main package directory, and temporarily copies them into the source directory during the build process.
 
 ## Features
@@ -16,6 +19,10 @@ Python package to automatically analyze, detect, and manage external dependencie
 - **Idempotent Operations**: Safely handles repeated runs without duplicating files
 - **Build Integration**: Seamlessly integrates with build tools like `uv build`, `pip build`, etc.
 - **Warning System**: Reports ambiguous imports that couldn't be resolved
+- **Subfolder Build Support**: Build subfolders as separate packages with automatic project root detection
+- **Smart Publishing**: Only uploads distribution files from the current build, filtering out old artifacts
+- **Auto-Detection**: Automatically finds project root and source directory when run from any subdirectory
+- **Authentication Helpers**: Auto-detects API tokens and uses correct username format
 
 ## Installation
 
@@ -44,16 +51,71 @@ uv add twine
 The simplest way to use this package is via the command-line interface:
 
 ```bash
-# Build with automatic dependency management
+# Build with automatic dependency management (from project root)
 python-package-folder --build-command "uv build"
 
 # Analyze dependencies without building
 python-package-folder --analyze-only
 
+# Build from any subdirectory - auto-detects project root and source directory
+cd tests/folder_structure/subfolder_to_build
+python-package-folder --analyze-only
+
 # Specify custom project root and source directory
 python-package-folder --project-root /path/to/project --src-dir /path/to/src --build-command "pip build"
 ```
 
+### Building from Subdirectories
+
+The tool can automatically detect the project root by searching for `pyproject.toml` in parent directories. This allows you to build subfolders of a main project as separate packages:
+
+```bash
+# From a subdirectory, the tool will:
+# 1. Find pyproject.toml in parent directories (project root)
+# 2. Use current directory as source if it contains Python files
+# 3. Build with dependencies from the parent project
+# 4. Create a temporary build config with subfolder-specific name and version
+
+cd my_project/subfolder_to_build
+python-package-folder --version "1.0.0" --publish pypi
+```
+
+**Important**: When building from a subdirectory, you **must** specify `--version` because subfolders are built as separate packages with their own version.
+
+The tool automatically:
+- Finds the project root by looking for `pyproject.toml` in parent directories
+- 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: creates a temporary `pyproject.toml` with:
+  - Package name derived from the subfolder name (or use `--package-name` to override)
+  - Version from `--version` argument
+  - Proper package path configuration for hatchling
+- Creates temporary `__init__.py` files if needed to make subfolders valid Python packages
+- **README handling for subfolder builds**:
+  - If a README file (README.md, README.rst, README.txt, or README) exists in the subfolder, it will be used instead of the parent README
+  - If no README exists in the subfolder, a minimal README with just the folder name will be created
+- Restores the original `pyproject.toml` after build (unless `--no-restore-versioning` is used)
+- Cleans up temporary `__init__.py` files after build
+
+**Subfolder Build Example:**
+```bash
+# Build a subfolder as a separate package
+cd tests/folder_structure/subfolder_to_build
+python-package-folder --version "0.1.0" --package-name "my-subfolder-package" --publish pypi
+
+# Build with a specific dependency group from parent pyproject.toml
+python-package-folder --version "0.1.0" --dependency-group "dev" --publish pypi
+```
+
+**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
+# Use the 'dev' dependency group from parent pyproject.toml
+python-package-folder --version "1.0.0" --dependency-group "dev" --publish pypi
+```
+
+The specified dependency group will be copied from the parent `pyproject.toml`'s `[dependency-groups]` section into the temporary `pyproject.toml` used for the subfolder build.
+
 ### Python API Usage
 
 You can also use the package programmatically:
@@ -169,6 +231,33 @@ The `--version` option:
 
 **Version Format**: Versions must follow PEP 440 (e.g., `1.2.3`, `1.2.3a1`, `1.2.3.post1`, `1.2.3.dev1`)
 
+### Subfolder Versioning
+
+When building from a subdirectory (not the main `src/` directory), you **must** specify `--version`:
+
+```bash
+# Build a subfolder as a separate package
+cd my_project/subfolder_to_build
+python-package-folder --version "1.0.0" --publish pypi
+
+# With custom package name
+python-package-folder --version "1.0.0" --package-name "my-custom-name" --publish pypi
+```
+
+For subfolder builds:
+- **Version is required**: The tool will error if `--version` is not provided
+- **Package name**: Automatically derived from the subfolder name (e.g., `subfolder_to_build` → `subfolder-to-build`)
+- **Temporary configuration**: Creates a temporary `pyproject.toml` with:
+  - Custom package name (from `--package-name` or derived)
+  - Specified version
+  - Correct package path for hatchling
+  - Dependency group from parent (if `--dependency-group` is specified)
+- **Package initialization**: Automatically creates `__init__.py` if the subfolder doesn't have one (required for hatchling)
+- **README handling**: 
+  - If a README file exists in the subfolder, it will be used instead of the parent README
+  - If no README exists in the subfolder, a minimal README with just the folder name will be created
+- **Auto-restore**: Original `pyproject.toml` is restored after build, and temporary `__init__.py` files are removed
+
 ### Python API for Version Management
 
 ```python
@@ -242,6 +331,21 @@ python-package-folder --publish pypi --skip-existing
 **For PyPI/TestPyPI:**
 - **Username**: Your PyPI username, or `__token__` for API tokens
 - **Password**: Your PyPI password or API token (recommended)
+- **Auto-detection**: If you provide an API token (starts with `pypi-`), the tool will automatically use `__token__` as the username, even if you entered a different username
+
+**Common Authentication Issues:**
+- **403 Forbidden**: Usually means you used your username instead of `__token__` with an API token. The tool now auto-detects this.
+- **TestPyPI vs PyPI**: TestPyPI requires a separate account and token from https://test.pypi.org/manage/account/token/
+
+### Smart File Filtering
+
+When publishing, the tool automatically filters distribution files to only upload those matching the current build:
+
+- **Package name matching**: Only uploads files for the package being built
+- **Version matching**: Only uploads files for the specified version
+- **Automatic cleanup**: Old build artifacts in `dist/` are ignored, preventing accidental uploads
+
+This ensures that when building a subfolder package, only that package's distribution files are uploaded, not files from previous builds of other packages.
 
 To get a PyPI API token:
 1. Go to https://pypi.org/manage/account/token/
@@ -330,7 +434,14 @@ options:
   --username USERNAME   Username for publishing (will prompt if not provided)
   --password PASSWORD   Password/token for publishing (will prompt if not provided)
   --skip-existing       Skip files that already exist on the repository
-  --version VERSION     Set a specific version before building (PEP 440 format)
+  --version VERSION     Set a specific version before building (PEP 440 format).
+                        Required for subfolder builds.
+  --package-name PACKAGE_NAME
+                        Package name for subfolder builds (default: derived from
+                        source directory name)
+  --dependency-group DEPENDENCY_GROUP
+                        Dependency group name from parent pyproject.toml to include
+                        in subfolder build
   --no-restore-versioning
                         Don't restore dynamic versioning after build
 ```
@@ -398,15 +509,19 @@ publisher = Publisher(
     repository=Repository.PYPI,
     dist_dir=Path("dist"),
     username="__token__",
-    password="pypi-xxxxx"
+    password="pypi-xxxxx",
+    package_name="my-package",  # Optional: filter files by package name
+    version="1.2.3"              # Optional: filter files by version
 )
 publisher.publish()
 ```
 
 **Methods:**
-- `publish(skip_existing: bool = False) -> None`: Publish the package
+- `publish(skip_existing: bool = False) -> None`: Publish the package (automatically filters by package_name/version if provided)
 - `publish_interactive(skip_existing: bool = False) -> None`: Publish with interactive credential prompts
 
+**Note**: When `package_name` and `version` are provided, only distribution files matching those parameters are uploaded. This prevents uploading old build artifacts.
+
 ### VersionManager
 
 Manages package version in pyproject.toml.
@@ -432,6 +547,39 @@ version_manager.restore_dynamic_versioning()
 - `get_current_version() -> str | None`: Get current version from pyproject.toml
 - `restore_dynamic_versioning() -> None`: Restore dynamic versioning configuration
 
+### SubfolderBuildConfig
+
+Manages temporary build configuration for subfolder builds.
+
+```python
+from python_package_folder import SubfolderBuildConfig
+from pathlib import Path
+
+config = SubfolderBuildConfig(
+    project_root=Path("."),
+    src_dir=Path("subfolder"),
+    package_name="my-subfolder",
+    version="1.0.0"
+)
+
+# Create temporary pyproject.toml
+config.create_temp_pyproject()
+
+# ... build process ...
+
+# Restore original configuration
+config.restore()
+```
+
+**Methods:**
+- `create_temp_pyproject() -> Path`: Create temporary `pyproject.toml` with subfolder-specific configuration
+- `restore() -> None`: Restore original `pyproject.toml` and clean up temporary files
+
+**Note**: This class automatically creates `__init__.py` files if needed to make subfolders valid Python packages. It also handles README files:
+- If a README exists in the subfolder, it will be used instead of the parent README
+- If no README exists in the subfolder, a minimal README with just the folder name will be created
+- The original parent README is backed up and restored after the build completes
+
 ## How It Works
 
 ### Build Process
@@ -454,13 +602,31 @@ version_manager.restore_dynamic_versioning()
 ### Publishing Process
 
 1. **Build Verification**: Ensures distribution files exist in the `dist/` directory
-2. **Credential Management**: 
+2. **File Filtering**: Automatically filters distribution files to only include those matching the current package name and version (prevents uploading old artifacts)
+3. **Credential Management**: 
    - Prompts for credentials if not provided
    - Uses `keyring` for secure storage (if available)
    - Supports both username/password and API tokens
-3. **Repository Configuration**: Configures the target repository (PyPI, TestPyPI, or Azure)
-4. **Upload**: Uses `twine` to upload distribution files to the repository
-5. **Verification**: Confirms successful upload
+   - Auto-detects API tokens and uses `__token__` as username
+4. **Repository Configuration**: Configures the target repository (PyPI, TestPyPI, or Azure)
+5. **Upload**: Uses `twine` to upload distribution files to the repository
+6. **Verification**: Confirms successful upload
+
+### Subfolder Build Process
+
+1. **Project Root Detection**: Searches parent directories for `pyproject.toml`
+2. **Source Directory Detection**: Uses current directory if it contains Python files, otherwise falls back to `project_root/src`
+3. **Package Initialization**: Creates temporary `__init__.py` if subfolder doesn't have one (required for hatchling)
+4. **README Handling**: 
+   - Checks for README files in the subfolder (README.md, README.rst, README.txt, or README)
+   - If found, copies the subfolder README to project root (backing up the original parent README)
+   - If not found, creates a minimal README with just the folder name
+5. **Configuration Creation**: Creates temporary `pyproject.toml` with:
+   - Subfolder-specific package name (derived or custom)
+   - Specified version
+   - Correct package path for hatchling
+6. **Build Execution**: Runs build command with all dependencies in place
+7. **Cleanup**: Restores original `pyproject.toml` and removes temporary `__init__.py`
 
 ## Requirements
 

python_package_folder-1.0.0/coverage.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
+  <linearGradient id="b" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <mask id="a">
+    <rect width="99" height="20" rx="3" fill="#fff"/>
+  </mask>
+  <g mask="url(#a)">
+    <path fill="#555" d="M0 0h63v20H0z"/>
+    <path fill="#dfb317" d="M63 0h36v20H63z"/>
+    <path fill="url(#b)" d="M0 0h99v20H0z"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+    <text x="31.5" y="14">coverage</text>
+    <text x="81" y="15" fill="#010101" fill-opacity=".3">64%</text>
+    <text x="81" y="14">64%</text>
+  </g>
+</svg>