Automating Python Script Execution with Poetry and pyproject.toml: A Comprehensive Guide from Build to Deployment

Core Mechanism of Poetry Script Configuration

In Python project development, Poetry serves as a modern dependency management and packaging tool, providing a unified configuration interface through the pyproject.toml file. The [tool.poetry.scripts] section is the key configuration element for automating command-line tools, maintaining design compatibility with setuptools' console_scripts entry point mechanism.

Correct Configuration of Script Entry Points

When configuring script entry points, the "module.path:function_name" format must be strictly followed. Common misconfigurations like "my_package_name:log_revision.py" result in AttributeError, as Poetry attempts to access the log_revision.py attribute rather than a function within the module.

A proper project structure example:

my_package
├── my_package
│   ├── __init__.py
│   └── log_revision.py
└── pyproject.toml

Define the entry function in log_revision.py:

def start():
    # Implement Git commit logging, parameter processing, and .whl file transfer logic
    print("Script execution started")

The corresponding pyproject.toml configuration should be:

[tool.poetry.scripts]
my-script = "my_package.log_revision:start"

After executing poetry install to install dependencies, the script can be run via poetry run my-script.

Command-Line Argument Processing Solutions

Since the [tool.poetry.scripts] configuration does not support direct parameter passing to entry functions, developers need to implement argument parsing using Python's standard library. The following example demonstrates handling build parameters with argparse:

import argparse

def start():
    parser = argparse.ArgumentParser(description='Process post-build tasks')
    parser.add_argument('--commit-hash', required=True, help='Git commit hash')
    parser.add_argument('--whl-path', required=True, help='.whl file path')
    
    args = parser.parse_args()
    
    # Database operations and FTP transfer logic
    save_to_database(args.commit_hash, args.whl_path)
    upload_to_ftp(args.whl_path)

Invocation method: poetry run my-script --commit-hash abc123 --whl-path dist/package-0.1.0.whl

Analysis of Alternative Execution Methods

For simple script execution needs, the poetry run python script.py command can be used directly. This approach requires no pyproject.toml configuration and is suitable for rapid prototyping or temporary tasks. For example:

poetry run python log_revision.py --param1 value1 --param2 value2

However, this method lacks formal project integration and is not suitable for long-term automated workflows.

Poetry Publish Function Configuration

The Repository ... is not defined error when using the poetry publish command typically occurs because repository information was not pre-configured in pyproject.toml. The correct configuration method is as follows:

[[tool.poetry.repositories]]
name = "my-repository"
url = "http://192.168.1.xxx/home/whl"

After configuration, the publish command should specify the repository name rather than the URL:

poetry publish -r my-repository -u hello -p world

Complete Workflow Implementation

Combining the technical points discussed above enables a complete automation workflow from building to deployment:

1. Configure script entry points and repository information in pyproject.toml
2. Implement script logic with argument parsing, integrating Git operations, database storage, and FTP transfer functionality
3. Chain poetry build and poetry run my-script commands through CI/CD tools or shell scripts
4. Use environment variables or configuration files to manage authentication information, avoiding hard-coded sensitive data

This architecture ensures repeatability and maintainability of post-build processing while fully leveraging the advantages of Poetry's ecosystem.