You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document outlines the strategic plan to transition the mlb-cli-py application from a local script to a fully distributable Python package available on PyPI.
1. Modernize Build and Packaging System
Objective: Transition from requirements.txt to a modern, PEP 621 compliant build system using pyproject.toml.
Tooling: Use build and setuptools (or a modern manager like Hatch or Poetry). For minimal disruption, standard setuptools configured via pyproject.toml is recommended.
Actions:
Create a pyproject.toml file at the repository root.
Define build system requirements (requires = ["setuptools>=61.0"]).
Define core dependencies (currently in requirements.txt) directly in pyproject.toml under dependencies.
2. Restructure for Distribution
Objective: Ensure the code is correctly structured as an importable Python package.
Actions:
Move mlb_cli.py into the app/ directory (or a new root package directory like mlb_cli/ containing app/) to avoid top-level module clashes.
Ensure all internal imports (e.g., from app.models...) correctly resolve when the package is installed globally.
Add an __init__.py to the root package directory to expose the main application runner.
3. Define CLI Entry Points
Objective: Allow users to launch the application from anywhere in their terminal after installing via pip install.
Actions:
In pyproject.toml, define a [project.scripts] section.
Map a global command (e.g., mlb-cli) to the main execution function: mlb-cli = "app.mlb_cli:main".
4. Metadata and Documentation Optimization
Objective: Ensure the package presents well on PyPI.
Actions:
Link the existing README.md in pyproject.toml so it renders as the PyPI project description.
Ensure LICENSE is correctly referenced.
Add a MANIFEST.in file if any non-Python files (like static assets or default configs) need to be included in the distribution, though currently, the app seems to be pure Python.
5. CI/CD Automation (GitHub Actions)
Objective: Automate the build and release process to ensure reliable and repeatable publishing.
Actions:
Create a .github/workflows/publish.yml file.
Configure the workflow to trigger on the creation of a new GitHub Release or a specific tag format (e.g., v*).
Use Trusted Publishing (OIDC) to authenticate with PyPI securely without storing long-lived passwords/tokens.
Automate the steps: checkout code, setup Python, install build, run python -m build, and use pypa/gh-action-pypi-publish to upload the distributions (sdist and wheel) to PyPI.
6. Local Testing and Verification
Objective: Validate the package builds and installs correctly before public release.
Actions:
Build the package locally: python3 -m build.
Test installation in an isolated virtual environment: pip install dist/*.whl.
Verify the mlb-cli global command works flawlessly and all TUI screens render as expected.
Perform a trial upload to TestPyPI before executing the production release.
Activity
conorpcleary commentedon May 17, 2026
Content generated by Gemini:
PyPI Release Implementation Strategy
This document outlines the strategic plan to transition the
mlb-cli-pyapplication from a local script to a fully distributable Python package available on PyPI.1. Modernize Build and Packaging System
Objective: Transition from
requirements.txtto a modern, PEP 621 compliant build system usingpyproject.toml.buildandsetuptools(or a modern manager likeHatchorPoetry). For minimal disruption, standardsetuptoolsconfigured viapyproject.tomlis recommended.pyproject.tomlfile at the repository root.requires = ["setuptools>=61.0"]).requirements.txt) directly inpyproject.tomlunderdependencies.2. Restructure for Distribution
Objective: Ensure the code is correctly structured as an importable Python package.
mlb_cli.pyinto theapp/directory (or a new root package directory likemlb_cli/containingapp/) to avoid top-level module clashes.from app.models...) correctly resolve when the package is installed globally.__init__.pyto the root package directory to expose the main application runner.3. Define CLI Entry Points
Objective: Allow users to launch the application from anywhere in their terminal after installing via
pip install.pyproject.toml, define a[project.scripts]section.mlb-cli) to the main execution function:mlb-cli = "app.mlb_cli:main".4. Metadata and Documentation Optimization
Objective: Ensure the package presents well on PyPI.
README.mdinpyproject.tomlso it renders as the PyPI project description.LICENSEis correctly referenced.MANIFEST.infile if any non-Python files (like static assets or default configs) need to be included in the distribution, though currently, the app seems to be pure Python.5. CI/CD Automation (GitHub Actions)
Objective: Automate the build and release process to ensure reliable and repeatable publishing.
.github/workflows/publish.ymlfile.v*).build, runpython -m build, and usepypa/gh-action-pypi-publishto upload the distributions (sdist and wheel) to PyPI.6. Local Testing and Verification
Objective: Validate the package builds and installs correctly before public release.
python3 -m build.pip install dist/*.whl.mlb-cliglobal command works flawlessly and all TUI screens render as expected.