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

{python_package_folder-1.0.0 → python_package_folder-1.1.1}/.vscode/settings.json

@@ -1,4 +1,5 @@
 {
+    "markdown.extension.toc.levels": "1..2",
     "python.testing.pytestArgs": [
         "tests"
     ],

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-package-folder
-Version: 1.0.0
+Version: 1.1.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>
@@ -18,42 +18,143 @@ Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.11
 Description-Content-Type: text/markdown
 
-# python-package-folder
+# 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)
 
-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.
+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.
+
+- [Use Cases](#use-cases)
+- [Features](#features)
+- [Installation and requirements](#installation-and-requirements)
+- [Quick Start](#quick-start)
+- [How does `python-package-folder` work?](#how-does-python-package-folder-work)
+- [Python API Usage](#python-api-usage)
+- [Working with sysappend](#working-with-sysappend)
+- [Publishing version Management](#publishing-version-management)
+- [Publishing Packages](#publishing-packages)
+- [Command Line Options](#command-line-options)
+- [API Reference](#api-reference)
+- [Development](#development)
+
+
+## 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 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
 
-- **Automatic Import Analysis**: Recursively parses all `.py` files to detect `import` and `from ... import ...` statements
-- **Smart Import Classification**: Distinguishes between:
-  - Standard library imports
-  - Third-party packages (from site-packages)
-  - Local imports (within the source directory)
-  - External imports (outside source directory but in the project)
-  - Ambiguous imports (unresolvable)
-- **External Dependency Detection**: Automatically finds modules and files that originate from outside the main package directory
-- **Temporary File Management**: Copies external dependencies into the source directory before build and cleans them up afterward
+- **Subfolder Build Support**: Build subfolders as separate packages with automatic project root detection
+  - 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
+  - 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.
-- **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
+- **Version Management**: 
+  - Set static versions for publishing (PEP 440 compliant)
+  - Temporarily override dynamic versioning during builds
+  - Automatic restoration of dynamic versioning after build
+- **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
 
-## Installation
 
-```bash
-pip install python-package-folder
-```
+## Installation and requirements
 
-Or using `uv`:
+Python >= 3.11 is required.
 
 ```bash
 uv add python-package-folder
+
+# or
+
+pip install python-package-folder
 ```
 
 **Note**: For publishing functionality, you'll also need `twine`:
@@ -64,30 +165,97 @@ pip install twine
 uv add twine
 ```
 
+**For secure credential storage**: `keyring` is optional but recommended (install with `pip install keyring`)
+
+
 ## Quick Start
 
-### Command Line Usage
+The simplest way to use this package is via the command-line interface
 
-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
-# Build with automatic dependency management (from project root)
-python-package-folder --build-command "uv build"
+# First cd to the specific subfolder
+cd src/subfolder_to_build_and_publish
 
-# Analyze dependencies without building
-python-package-folder --analyze-only
+# Build and publish any subdirectory of your repo to TestPyPi (https://test.pypi.org/) 
+python-package-folder --publish testpypi --version 0.0.2
 
-# Build from any subdirectory - auto-detects project root and source directory
-cd tests/folder_structure/subfolder_to_build
+# 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:
+
+```python
 # 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
+## How does `python-package-folder` work?
+
+
+### Build Process
+
+1. **Import Extraction**: Uses Python's AST module to parse all `.py` files and extract import statements
+2. **Classification**: Each import is classified as:
+   - **stdlib**: Standard library modules
+   - **third_party**: Packages installed in site-packages
+   - **local**: Modules within the source directory
+   - **external**: Modules outside source directory but in the project
+   - **ambiguous**: Cannot be resolved
+3. **Dependency Resolution**: For external imports, the tool resolves the file path by checking:
+   - Parent directories of the source directory
+   - Project root and its subdirectories
+   - Relative import paths
+4. **File Copying**: External dependencies are temporarily copied into the source directory
+5. **Build Execution**: Your build command runs with all dependencies in place
+6. **Cleanup**: All temporarily copied files are removed after build
+
+### Publishing Process
+
+1. **Build Verification**: Ensures distribution files exist in the `dist/` directory
+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
+   - 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
 
-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:
+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`
+
+### How does building from Subdirectories work?
+
+This is useful for monorepos containing many subfolders that may need publishing as stand-alone packages for external usage.  
+The tool automatically detects 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:
@@ -100,7 +268,7 @@ 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.
+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
@@ -136,7 +304,7 @@ 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
+## Python API Usage
 
 You can also use the package programmatically:
 
@@ -180,37 +348,7 @@ def build_command():
 manager.run_build(build_command)
 ```
 
-## Use Cases
-
-### 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
-
-### Working with sysappend
+## Working with sysappend
 
 This package works well with projects using [sysappend](https://pypi.org/project/sysappend/) for flexible import management. When you have imports like:
 
@@ -224,10 +362,11 @@ from folder_structure.utility_folder.some_utility import print_something
 
 The package will correctly identify and copy external dependencies even when they're referenced without full package paths.
 
-## Version Management
+## Publishing version Management
 
 The package supports both dynamic versioning (from git tags) and manual version specification.
 
+
 ### Manual Version Setting
 
 You can manually set a version before building and publishing:
@@ -251,6 +390,7 @@ 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`:
@@ -278,6 +418,7 @@ For subfolder builds:
   - 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
@@ -318,6 +459,7 @@ When you use `--version`, the package temporarily switches to static versioning
 
 The package includes built-in support for publishing to PyPI, TestPyPI, and Azure Artifacts.
 
+
 ### Command Line Publishing
 
 Publish after building:
@@ -346,6 +488,7 @@ python-package-folder --publish pypi --username __token__ --password pypi-xxxxx
 python-package-folder --publish pypi --skip-existing
 ```
 
+
 ### Credentials
 
 **For PyPI/TestPyPI:**
@@ -357,6 +500,7 @@ python-package-folder --publish pypi --skip-existing
 - **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:
@@ -377,6 +521,7 @@ To get a PyPI API token:
 - **Password**: Personal Access Token (PAT) with packaging permissions
 - **Repository URL**: Your Azure Artifacts feed URL
 
+
 ### Python API Publishing
 
 You can also publish programmatically:
@@ -417,6 +562,7 @@ publisher = Publisher(
 publisher.publish()
 ```
 
+
 ### Credential Storage
 
 The package uses the `keyring` library (if installed) to securely store credentials. Credentials are stored per repository and will be reused on subsequent runs.
@@ -600,59 +746,6 @@ config.restore()
 - 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
-
-1. **Import Extraction**: Uses Python's AST module to parse all `.py` files and extract import statements
-2. **Classification**: Each import is classified as:
-   - **stdlib**: Standard library modules
-   - **third_party**: Packages installed in site-packages
-   - **local**: Modules within the source directory
-   - **external**: Modules outside source directory but in the project
-   - **ambiguous**: Cannot be resolved
-3. **Dependency Resolution**: For external imports, the tool resolves the file path by checking:
-   - Parent directories of the source directory
-   - Project root and its subdirectories
-   - Relative import paths
-4. **File Copying**: External dependencies are temporarily copied into the source directory
-5. **Build Execution**: Your build command runs with all dependencies in place
-6. **Cleanup**: All temporarily copied files are removed after build
-
-### Publishing Process
-
-1. **Build Verification**: Ensures distribution files exist in the `dist/` directory
-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
-   - 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 >= 3.11
-- **For publishing**: `twine` is required (install with `pip install twine`)
-- **For secure credential storage**: `keyring` is optional but recommended (install with `pip install keyring`)
 
 ## Development
 
@@ -673,7 +766,7 @@ uv run pytest
 make lint
 ```
 
-### Project Structure
+### Project Structure 
 
 ```
 python-package-folder/
@@ -693,18 +786,10 @@ python-package-folder/
 └── pyproject.toml
 ```
 
-## License
+## License  <!-- omit from toc -->
 
 MIT License - see LICENSE file for details
 
-## Contributing
+## Contributing  <!-- omit from toc -->
 
 Contributions are welcome! Please feel free to submit a Pull Request.
-
-## Author
-
-Alessio Lombardi - [GitHub](https://github.com/alelom)
-
-## Related Projects
-
-- [sysappend](https://pypi.org/project/sysappend/) - Flexible import management for Python projects