python-package-folder 4.3.6__tar.gz → 5.0.1__tar.gz

python_package_folder-5.0.1/.cursor/plans/replace_node.js_semantic-release_with_custom_python_implementation_64e05e1a.plan.md

@@ -0,0 +1,268 @@
+---
+name: Replace Node.js semantic-release with custom Python implementation
+overview: Replace the Node.js semantic-release dependency with a pure Python implementation that calculates versions from conventional commits, queries registries for baseline versions, and filters commits by subfolder path. This eliminates the push permission requirement and Node.js dependency.
+todos: []
+---
+
+# Replace Node.js semantic-release with Custom Python Implementation
+
+## Overview
+
+Replace the Node.js `semantic-release` implementation with a pure Python solution that:
+
+- Calculates next version from conventional commits (no push permissions needed)
+- Queries registries (PyPI/TestPyPI/Azure) for baseline versions
+- Filters commits by subfolder path for monorepo support
+- Eliminates Node.js dependency
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Version Resolution Flow                    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+        ┌─────────────────────────────────────┐
+        │  Query Registry (PyPI/Azure/etc)     │
+        │  for latest published version        │
+        └─────────────────────────────────────┘
+                      │
+        ┌─────────────┴─────────────┐
+        │                           │
+        ▼                           ▼
+    Success                      Failure
+        │                           │
+        ▼                           ▼
+  Use registry              Query Git Tags
+    version                 (v1.2.3 or
+        │                   package-v1.2.3)
+        │                           │
+        └─────────────┬─────────────┘
+                      │
+                      ▼
+        ┌─────────────────────────────┐
+        │  Get commits since baseline │
+        │  (filter by subfolder path) │
+        └─────────────────────────────┘
+                      │
+                      ▼
+        ┌─────────────────────────────┐
+        │  Parse conventional commits │
+        │  (feat/fix/BREAKING CHANGE) │
+        └─────────────────────────────┘
+                      │
+                      ▼
+        ┌─────────────────────────────┐
+        │  Determine bump type        │
+        │  (major/minor/patch)        │
+        └─────────────────────────────┘
+                      │
+                      ▼
+        ┌─────────────────────────────┐
+        │  Calculate next version     │
+        │  (baseline + bump)          │
+        └─────────────────────────────┘
+```
+
+## Implementation Details
+
+### 1. Create New Python Module: `src/python_package_folder/version_calculator.py`
+
+**Functions to implement:**
+
+- `query_registry_version(package_name: str, repository: str, repository_url: str | None = None) -> str | None`
+  - Query PyPI/TestPyPI JSON API (`https://pypi.org/pypi/{package}/json`)
+  - Query Azure Artifacts (basic support, fallback on failure)
+  - Return latest version string or None
+
+- `get_latest_git_tag(project_root: Path, package_name: str | None = None, is_subfolder: bool = False) -> str | None`
+  - For main package: look for tags matching `v{version}` (e.g., `v1.2.3`)
+  - For subfolder: look for tags matching `{package-name}-v{version}` (e.g., `my-package-v1.2.3`)
+  - Use `git tag --list` and parse version from tag
+  - Return latest version or None
+
+- `get_commits_since(project_root: Path, baseline_version: str, subfolder_path: Path | None = None) -> list[str]`
+  - Use `git log --oneline` to get commits since baseline
+  - If `subfolder_path` provided, use `git log -- <subfolder_path>` to filter
+  - Return list of commit messages
+
+- `parse_commit_for_bump(commit_message: str) -> str | None`
+  - Parse conventional commit format following [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md) as used by semantic-release
+  - Return `"major"`, `"minor"`, `"patch"`, or `None`
+  - **Breaking Change Detection (Major bump):**
+    - `BREAKING CHANGE:` in commit footer (body)
+    - `!` after type/scope: `feat!:`, `feat(scope)!:`, `fix!:`, etc.
+  - **Version Bump Rules:**
+    - `feat:` → `minor` (new feature)
+    - `fix:` → `patch` (bug fix)
+    - `perf:` → `patch` (performance improvement)
+    - **No version bump** (ignored): `docs:`, `style:`, `refactor:`, `test:`, `build:`, `ci:`, `chore:`, `revert:`
+  - All commit types supported by semantic-release Angular preset are recognized, but only `feat`, `fix`, and `perf` affect version bumps
+
+- `calculate_next_version(baseline_version: str, commits: list[str], subfolder_path: Path | None = None) -> str | None`
+  - Get commits since baseline (filtered by subfolder if needed)
+  - Parse each commit for bump type
+  - Determine highest bump (major > minor > patch)
+  - Increment version: `1.2.3` + `minor` → `1.3.0`
+  - Return next version or None if no changes
+
+- `resolve_version(project_root: Path, package_name: str | None = None, subfolder_path: Path | None = None, repository: str | None = None, repository_url: str | None = None) -> tuple[str | None, str | None]`
+  - Main entry point (replaces `resolve_version_via_semantic_release`)
+  - Try registry query first, fallback to git tags
+  - Calculate next version from commits
+  - Return `(version, error_message)` tuple
+
+### 2. Update `src/python_package_folder/python_package_folder.py`
+
+**Changes:**
+
+- Replace `resolve_version_via_semantic_release()` call with `resolve_version()` from `version_calculator`
+- Remove `check_node_available()` function (no longer needed)
+- Remove Node.js error messages
+- Update imports: `from python_package_folder.version_calculator import resolve_version`
+
+### 3. Remove Node.js Dependencies
+
+**Files to delete:**
+
+- `src/python_package_folder/scripts/get-next-version.cjs`
+- `scripts/get-next-version.cjs` (if exists)
+
+**Files to update:**
+
+- `pyproject.toml`: Remove any references to Node.js scripts in build hooks
+- `src/python_package_folder/_hatch_build.py`: Remove script inclusion logic (if present)
+- `MANIFEST.in`: Remove script inclusion (if present)
+
+### 4. Update Documentation: `README.md`
+
+**Sections to update:**
+
+- **"Automatic Version Resolution" section:**
+  - Remove Node.js/semantic-release setup instructions
+  - Update to describe Python-native implementation
+  - Keep registry query explanation
+  - Update commit filtering explanation (now native Python)
+  - **Add architecture diagram** (mermaid format) showing version resolution flow:
+```mermaid
+flowchart TD
+    Start[Version Resolution] --> QueryRegistry[Query Registry<br/>PyPI/Azure/etc]
+    QueryRegistry -->|Success| UseRegistry[Use Registry Version]
+    QueryRegistry -->|Failure| QueryGitTags[Query Git Tags<br/>v1.2.3 or package-v1.2.3]
+    UseRegistry --> GetCommits[Get Commits Since Baseline<br/>filter by subfolder path]
+    QueryGitTags --> GetCommits
+    GetCommits --> ParseCommits[Parse Conventional Commits<br/>feat/fix/perf/BREAKING CHANGE]
+    ParseCommits --> DetermineBump[Determine Bump Type<br/>major/minor/patch]
+    DetermineBump --> CalculateVersion[Calculate Next Version<br/>baseline + bump]
+    CalculateVersion --> End[Return Version]
+```
+
+  - **Add "Supported Commit Types" subsection:**
+    - Document all Angular commit types supported (following [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md) as used by [semantic-release](https://semantic-release.gitbook.io/semantic-release/))
+    - **Version Bump Types:**
+      - `feat:` → **Minor** (new feature)
+      - `fix:` → **Patch** (bug fix)
+      - `perf:` → **Patch** (performance improvement)
+      - Breaking changes (any type with `!` or `BREAKING CHANGE:` footer) → **Major**
+    - **Ignored Types** (no version bump): `docs:`, `style:`, `refactor:`, `test:`, `build:`, `ci:`, `chore:`, `revert:`
+    - **Breaking Change Detection:**
+      - `BREAKING CHANGE:` in commit footer/body
+      - `!` after type: `feat!:`, `fix!:`, `feat(scope)!:`
+    - Include examples for each bump type with actual commit message examples
+    - Reference: "This implementation follows the same conventions as [semantic-release](https://semantic-release.gitbook.io/semantic-release/) using the Angular preset"
+
+- **"Requirements" section:**
+  - Remove: "Install semantic-release globally"
+  - Remove: "Install semantic-release-commit-filter"
+  - Keep: "Conventional commits required"
+  - Add note: "Follows [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md) as used by [semantic-release](https://semantic-release.gitbook.io/semantic-release/)"
+
+- **"Subfolder Versioning" section:**
+  - Update to reflect Python-native commit filtering
+  - Remove references to `semantic-release-commit-filter`
+
+### 5. Add Tests: `tests/test_version_calculator.py`
+
+**Test cases:**
+
+- `test_query_pypi_version()` - Mock HTTP request to PyPI API
+- `test_query_testpypi_version()` - Mock HTTP request to TestPyPI API
+- `test_query_azure_artifacts_version()` - Mock Azure Artifacts request (basic)
+- `test_get_latest_git_tag_main_package()` - Test `v1.2.3` tag parsing
+- `test_get_latest_git_tag_subfolder()` - Test `package-v1.2.3` tag parsing
+- `test_get_commits_since()` - Test git log filtering
+- `test_get_commits_since_with_subfolder()` - Test subfolder path filtering
+- `test_parse_commit_for_bump_major_breaking_footer()` - Test `BREAKING CHANGE:` in footer
+- `test_parse_commit_for_bump_major_exclamation()` - Test `feat!:`, `fix!:` syntax
+- `test_parse_commit_for_bump_major_exclamation_with_scope()` - Test `feat(scope)!:` syntax
+- `test_parse_commit_for_bump_minor()` - Test `feat:` detection
+- `test_parse_commit_for_bump_patch_fix()` - Test `fix:` detection
+- `test_parse_commit_for_bump_patch_perf()` - Test `perf:` detection
+- `test_parse_commit_for_bump_none()` - Test ignored commit types (docs, style, refactor, test, build, ci, chore, revert)
+- `test_calculate_next_version_patch()` - Test version increment (1.2.3 → 1.2.4)
+- `test_calculate_next_version_minor()` - Test version increment (1.2.3 → 1.3.0)
+- `test_calculate_next_version_major()` - Test version increment (1.2.3 → 2.0.0)
+- `test_calculate_next_version_no_changes()` - Test None when no relevant commits
+- `test_resolve_version_registry_first()` - Integration test with registry query
+- `test_resolve_version_git_fallback()` - Integration test with git tag fallback
+- `test_resolve_version_subfolder()` - Integration test for subfolder builds
+
+**Test utilities:**
+
+- Use `pytest` fixtures for temporary git repositories
+- Use `unittest.mock` to mock HTTP requests and git commands
+- Use `subprocess` mocking for git commands
+
+### 6. Update Integration Tests
+
+**Files to check:**
+
+- `tests/test_subfolder_build.py` - May need updates if it tests version resolution
+- Any other tests that mock or test `resolve_version_via_semantic_release`
+
+### 7. Dependencies
+
+**Add to `pyproject.toml` (if not already present):**
+
+- `requests>=2.0.0` (for registry queries - already in lock file)
+
+**Remove:**
+
+- Any Node.js/npm related dependencies or build hooks
+
+## Testing Strategy
+
+1. **Unit tests**: Test each function in isolation with mocks
+2. **Integration tests**: Test full version resolution flow with temporary git repos
+3. **Manual testing**: Test against this repository's actual git history
+4. **CI testing**: Ensure tests pass in GitHub Actions (no Node.js needed)
+
+## Migration Notes
+
+- **Backward compatibility**: The function signature `resolve_version()` matches the old `resolve_version_via_semantic_release()` signature, so CLI code doesn't need changes
+- **Error messages**: Update error messages to remove Node.js references
+- **Documentation**: Update all docs to reflect Python-native approach
+
+## Files to Create/Modify
+
+**New files:**
+
+- `src/python_package_folder/version_calculator.py` (~300-400 lines)
+
+**Modified files:**
+
+- `src/python_package_folder/python_package_folder.py` (replace function call, remove Node.js checks)
+- `README.md` (update documentation)
+- `tests/test_version_calculator.py` (new test file)
+
+**Deleted files:**
+
+- `src/python_package_folder/scripts/get-next-version.cjs`
+- `scripts/get-next-version.cjs` (if exists)
+
+**Potentially modified:**
+
+- `pyproject.toml` (remove build hooks for scripts)
+- `src/python_package_folder/_hatch_build.py` (remove script inclusion)
+- `MANIFEST.in` (remove script inclusion)

{python_package_folder-4.3.6 → python_package_folder-5.0.1}/.github/workflows/ci.yml

@@ -56,9 +56,6 @@ jobs:
       - name: Install all dependencies
         run: uv sync --all-extras
 
-      - name: Run linting
-        run: uv run ruff check .
-
       - name: Check formatting
         continue-on-error: true
         run: uv run ruff format --check .

python_package_folder-5.0.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: python-package-folder
+Version: 5.0.1
+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>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.11
+Requires-Dist: requests>=2.0.0
+Description-Content-Type: text/markdown
+
+# python-package-folder <!-- omit from toc -->
+
+[![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)
+
+Easily build and publish any target folder in a repository, including subfolders of a monorepo.  
+Together with [sysappend](https://pypi.org/project/sysappend/), this library makes relative imports, flexible import management, and package publishing a breeze.
+
+## Documentation
+
+- [Installation and Requirements](docs/INSTALLATION.md)
+- [Usage Guide](docs/USAGE.md) - How it works, Python API, subfolder builds
+- [Version Resolution](docs/VERSION_RESOLUTION.md) - Manual and automatic versioning with conventional commits
+- [Publishing Packages](docs/PUBLISHING.md) - Publishing to PyPI, TestPyPI, and Azure Artifacts
+- [API Reference](docs/REFERENCE.md) - Command-line options and Python API
+- [Development](docs/DEVELOPMENT.md) - Contributing and project structure
+
+## Use Cases
+
+### 1) Publishing a Subfolder from src/ in a Monorepo
+
+If you have a monorepo structure with multiple packages in `src/`:
+
+```
+project/
+├── src/
+│   ├── core_package/
+│   │   ├── __init__.py
+│   │   ├── core.py
+│   │   └── README.md
+│   ├── api_package/
+│   │   ├── __init__.py
+│   │   ├── api.py
+│   │   └── README.md
+│   └── utils_package/
+│       ├── __init__.py
+│       ├── utils.py
+│       └── README.md
+├── shared/
+│   └── common.py
+└── pyproject.toml
+```
+
+You can build and publish any subfolder from `src/` as a standalone package:
+
+```bash
+# Navigate to the subfolder you want to publish
+cd src/api_package
+
+# Build and publish to TestPyPI with version 1.2.0
+python-package-folder --publish testpypi --version 1.2.0
+
+# Or publish to PyPI with automatic version resolution via conventional commits
+python-package-folder --publish pypi
+
+# Or publish to PyPI with a custom package name
+python-package-folder --publish pypi --version 1.2.0 --package-name "my-api-package"
+
+# Include a specific dependency group from the parent pyproject.toml
+python-package-folder --publish pypi --version 1.2.0 --dependency-group "dev"
+```
+
+The tool will automatically:
+1. Detect the project root (where `pyproject.toml` is located)
+2. Use `src/api_package` as the source directory
+3. Copy any external dependencies (like `shared/common.py`) into the package before building
+4. Use the subfolder's README if present, or create a minimal one
+5. Create a temporary `pyproject.toml` with the subfolder's package name and version
+6. Build and publish the package
+7. Clean up all temporary files and restore the original `pyproject.toml`
+
+This is especially useful for monorepos where you want to publish individual packages independently while sharing common code.
+
+
+### 2) Building Packages with Shared Code
+
+If your project structure looks like this:
+
+```
+project/
+├── src/
+│   └── my_package/
+│       └── main.py
+├── shared/
+│   ├── utils.py
+│   └── helpers.py
+└── pyproject.toml
+```
+
+And `main.py` imports from `shared/`:
+
+```python
+from shared.utils import some_function
+from shared.helpers import Helper
+```
+
+This package will automatically:
+1. Detect that `shared/` is outside `src/`
+2. Copy `shared/` into `src/` before building
+3. Build your package with all dependencies included
+4. Clean up the copied files after build
+
+## Features
+
+- **Subfolder Build Support**: Build subfolders as separate packages with automatic detection and configuration
+  - **Automatic subfolder detection**: Detects when building a subfolder (not the main `src/` directory)
+  - Creates any needed file for publishing automatically, cleaning up if not originally in the subfolder after the build/publish process. E.g. copies external dependencies into the source directory before build and cleans them up afterward; temporary `__init__.py` creation for non-package subfolders; uses subfolder README if present, otherwise creates minimal README
+  - Automatic package name derivation from subfolder name
+  - Automatic temporary `pyproject.toml` creation with correct package structure
+  - Dependency group selection: specify which dependency group from parent `pyproject.toml` to include.
+  
+- **Smart Import Classification and analysis**:
+  - Recursively parses all `.py` files to detect `import` and `from ... import ...` statements
+  - Handles external dependencies (modules and files that originate from outside the main package directory), and distinguishes standard library imports, 3rd-party packages (from site-packages), local/external/relative/ambiguous imports.
+
+- **Idempotent Operations**: Safely handles repeated runs without duplicating files
+- **Build Integration**: Seamlessly integrates with build tools like `uv build`, `pip build`, etc.
+- **Version Management**: 
+  - Set static versions for publishing (PEP 440 compliant)
+  - Temporarily override dynamic versioning during builds
+  - Automatic restoration of dynamic versioning after build
+  - **Automatic version resolution** via conventional commits (Python-native, no Node.js required)
+- **Package Publishing**:
+  - Uses twine to publish the built folder/subfolder 
+  - Handles publishing to to PyPI, TestPyPI, or Azure Artifacts, with interactive credential prompts, secure storage support
+
+## Quick Start
+
+The simplest way to use this package is via the command-line interface
+
+**Build/publish a specific subfolder in a repository**
+
+Useful for monorepos containing many subfolders that may need publishing as stand-alone packages for external usage.
+
+```bash
+# First cd to the specific subfolder
+cd src/subfolder_to_build_and_publish
+
+# Build and publish any subdirectory of your repo to TestPyPi (https://test.pypi.org/)
+# Version can be provided explicitly or resolved automatically via conventional commits
+python-package-folder --publish testpypi --version 0.0.2
+
+# Or let the tool determine the next version automatically from conventional commits
+python-package-folder --publish testpypi
+
+# Only analyse (no building)
+cd src/subfolder_to_build_and_publish
+python-package-folder --analyze-only
+
+# Only build
+cd src/subfolder_to_build_and_publish
+python-package-folder
+
+# Build with automatic dependency management
+python-package-folder --build-command "uv build"
+```
+
+You can also target a specific subfolder via commandline, rather than `cd`ing there:
+
+```bash
+# Specify custom project root and source directory
+python-package-folder --project-root /path/to/project --src-dir /path/to/src --build-command "pip build"
+```
+
+## License <!-- omit from toc -->
+
+MIT License - see LICENSE file for details
+
+## Contributing <!-- omit from toc -->
+
+Contributions are welcome! Please feel free to submit a Pull Request.

python_package_folder-5.0.1/README.md

@@ -0,0 +1,171 @@
+# python-package-folder <!-- omit from toc -->
+
+[![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)
+
+Easily build and publish any target folder in a repository, including subfolders of a monorepo.  
+Together with [sysappend](https://pypi.org/project/sysappend/), this library makes relative imports, flexible import management, and package publishing a breeze.
+
+## Documentation
+
+- [Installation and Requirements](docs/INSTALLATION.md)
+- [Usage Guide](docs/USAGE.md) - How it works, Python API, subfolder builds
+- [Version Resolution](docs/VERSION_RESOLUTION.md) - Manual and automatic versioning with conventional commits
+- [Publishing Packages](docs/PUBLISHING.md) - Publishing to PyPI, TestPyPI, and Azure Artifacts
+- [API Reference](docs/REFERENCE.md) - Command-line options and Python API
+- [Development](docs/DEVELOPMENT.md) - Contributing and project structure
+
+## Use Cases
+
+### 1) Publishing a Subfolder from src/ in a Monorepo
+
+If you have a monorepo structure with multiple packages in `src/`:
+
+```
+project/
+├── src/
+│   ├── core_package/
+│   │   ├── __init__.py
+│   │   ├── core.py
+│   │   └── README.md
+│   ├── api_package/
+│   │   ├── __init__.py
+│   │   ├── api.py
+│   │   └── README.md
+│   └── utils_package/
+│       ├── __init__.py
+│       ├── utils.py
+│       └── README.md
+├── shared/
+│   └── common.py
+└── pyproject.toml
+```
+
+You can build and publish any subfolder from `src/` as a standalone package:
+
+```bash
+# Navigate to the subfolder you want to publish
+cd src/api_package
+
+# Build and publish to TestPyPI with version 1.2.0
+python-package-folder --publish testpypi --version 1.2.0
+
+# Or publish to PyPI with automatic version resolution via conventional commits
+python-package-folder --publish pypi
+
+# Or publish to PyPI with a custom package name
+python-package-folder --publish pypi --version 1.2.0 --package-name "my-api-package"
+
+# Include a specific dependency group from the parent pyproject.toml
+python-package-folder --publish pypi --version 1.2.0 --dependency-group "dev"
+```
+
+The tool will automatically:
+1. Detect the project root (where `pyproject.toml` is located)
+2. Use `src/api_package` as the source directory
+3. Copy any external dependencies (like `shared/common.py`) into the package before building
+4. Use the subfolder's README if present, or create a minimal one
+5. Create a temporary `pyproject.toml` with the subfolder's package name and version
+6. Build and publish the package
+7. Clean up all temporary files and restore the original `pyproject.toml`
+
+This is especially useful for monorepos where you want to publish individual packages independently while sharing common code.
+
+
+### 2) Building Packages with Shared Code
+
+If your project structure looks like this:
+
+```
+project/
+├── src/
+│   └── my_package/
+│       └── main.py
+├── shared/
+│   ├── utils.py
+│   └── helpers.py
+└── pyproject.toml
+```
+
+And `main.py` imports from `shared/`:
+
+```python
+from shared.utils import some_function
+from shared.helpers import Helper
+```
+
+This package will automatically:
+1. Detect that `shared/` is outside `src/`
+2. Copy `shared/` into `src/` before building
+3. Build your package with all dependencies included
+4. Clean up the copied files after build
+
+## Features
+
+- **Subfolder Build Support**: Build subfolders as separate packages with automatic detection and configuration
+  - **Automatic subfolder detection**: Detects when building a subfolder (not the main `src/` directory)
+  - Creates any needed file for publishing automatically, cleaning up if not originally in the subfolder after the build/publish process. E.g. copies external dependencies into the source directory before build and cleans them up afterward; temporary `__init__.py` creation for non-package subfolders; uses subfolder README if present, otherwise creates minimal README
+  - Automatic package name derivation from subfolder name
+  - Automatic temporary `pyproject.toml` creation with correct package structure
+  - Dependency group selection: specify which dependency group from parent `pyproject.toml` to include.
+  
+- **Smart Import Classification and analysis**:
+  - Recursively parses all `.py` files to detect `import` and `from ... import ...` statements
+  - Handles external dependencies (modules and files that originate from outside the main package directory), and distinguishes standard library imports, 3rd-party packages (from site-packages), local/external/relative/ambiguous imports.
+
+- **Idempotent Operations**: Safely handles repeated runs without duplicating files
+- **Build Integration**: Seamlessly integrates with build tools like `uv build`, `pip build`, etc.
+- **Version Management**: 
+  - Set static versions for publishing (PEP 440 compliant)
+  - Temporarily override dynamic versioning during builds
+  - Automatic restoration of dynamic versioning after build
+  - **Automatic version resolution** via conventional commits (Python-native, no Node.js required)
+- **Package Publishing**:
+  - Uses twine to publish the built folder/subfolder 
+  - Handles publishing to to PyPI, TestPyPI, or Azure Artifacts, with interactive credential prompts, secure storage support
+
+## Quick Start
+
+The simplest way to use this package is via the command-line interface
+
+**Build/publish a specific subfolder in a repository**
+
+Useful for monorepos containing many subfolders that may need publishing as stand-alone packages for external usage.
+
+```bash
+# First cd to the specific subfolder
+cd src/subfolder_to_build_and_publish
+
+# Build and publish any subdirectory of your repo to TestPyPi (https://test.pypi.org/)
+# Version can be provided explicitly or resolved automatically via conventional commits
+python-package-folder --publish testpypi --version 0.0.2
+
+# Or let the tool determine the next version automatically from conventional commits
+python-package-folder --publish testpypi
+
+# Only analyse (no building)
+cd src/subfolder_to_build_and_publish
+python-package-folder --analyze-only
+
+# Only build
+cd src/subfolder_to_build_and_publish
+python-package-folder
+
+# Build with automatic dependency management
+python-package-folder --build-command "uv build"
+```
+
+You can also target a specific subfolder via commandline, rather than `cd`ing there:
+
+```bash
+# Specify custom project root and source directory
+python-package-folder --project-root /path/to/project --src-dir /path/to/src --build-command "pip build"
+```
+
+## License <!-- omit from toc -->
+
+MIT License - see LICENSE file for details
+
+## Contributing <!-- omit from toc -->
+
+Contributions are welcome! Please feel free to submit a Pull Request.

{python_package_folder-4.3.6 → python_package_folder-5.0.1}/coverage.svg

@@ -14,7 +14,7 @@
   <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>
+    <text x="81" y="15" fill="#010101" fill-opacity=".3">68%</text>
+    <text x="81" y="14">68%</text>
   </g>
 </svg>