DEV Community

Abhinav
Abhinav

Posted on

Shipping 1.0.0: From Local Repo to a Published Python Package

#cli #python #opensource

Overview

This post documents releasing version 1.0.0 of the project to Python’s ecosystem. It covers: tooling choice, release steps, lessons learned, user testing feedback, required code changes, and installation/usage instructions.

Tooling & Registry Choices

Release Workflow (Detailed)

  1. Clean repo 
   git status
Enter fullscreen mode Exit fullscreen mode
  1. Update version in pyproject.toml (set to 1.0.0).
  2. Run tests 
   python -m pytest
Enter fullscreen mode Exit fullscreen mode
  1. (Optional) Add or confirm __all__ exports and __init__.py.
  2. Build distributions 
   python -m pip install --upgrade build twine
   python -m build
   ls dist/
Enter fullscreen mode Exit fullscreen mode
  1. Validate artifacts 
   python -m twine check dist/*
Enter fullscreen mode Exit fullscreen mode
  1. Tag release 
   git tag -a v1.0.0 -m "Release 1.0.0"
   git push origin v1.0.0
Enter fullscreen mode Exit fullscreen mode
  1. Upload to TestPyPI 
   python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
Enter fullscreen mode Exit fullscreen mode
  1. Fresh environment install test 
   python -m venv .venv-test
   source .venv-test/bin/activate
   python -m pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple your-package-name
   python -c "import your_package; print(your_package.__version__)"
Enter fullscreen mode Exit fullscreen mode

  1. Upload to PyPI

    python -m twine upload dist/*

  2. Update README: add install, usage, changelog section.

  3. Optional: create a GitHub Release referencing tag.

Minimal pyproject.toml Example 

[project]
name = "your-package-name"
version = "1.0.0"
description = "Concise description of the package."
readme = "README.md"
requires-python = ">=3.9"
license = { text = "MIT" }
authors = [
  { name = "Your Name", email = "you@example.com" }
]
keywords = ["context", "repository", "utility"]
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
  "Operating System :: OS Independent",
  "Development Status :: 5 - Production/Stable"
]

[project.optional-dependencies]
dev = ["pytest", "build", "twine"]

[tool.setuptools]
packages = ["your_package"]
Enter fullscreen mode Exit fullscreen mode

Code Adjustments

  • Added project metadata in pyproject.toml.
  • Ensured package has your_package/__init__.py.
  • Exposed __version__ inside package to avoid duplication.
  • Expanded README for install and usage. No functional logic changes required.

Example __init__.py:

__version__ = "1.0.0"

from .core import main_tool  # example public API
Enter fullscreen mode Exit fullscreen mode

User Testing Session Notes

Observed issues:

  • Missing virtual environment usage (user attempted global install).
  • Initial confusion about required Python version.
  • User looked for quick start; added a “5‑line usage” block. Resolutions:
  • Added explicit venv commands.
  • Added Python version badge.
  • Clarified import path with a minimal working snippet.

Installation (Users)

Production (PyPI):

python -m pip install your-package-name
Enter fullscreen mode Exit fullscreen mode

TestPyPI (staging validation):

python -m pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple your-package-name
Enter fullscreen mode Exit fullscreen mode

Upgrade:

python -m pip install -U your-package-name
Enter fullscreen mode Exit fullscreen mode

Uninstall:

python -m pip uninstall your-package-name
Enter fullscreen mode Exit fullscreen mode

Quick Start 

from your_package import main_tool

result = main_tool("input text")
print(result)
Enter fullscreen mode Exit fullscreen mode

CLI example (if provided):

your-package-name --help
your-package-name run --input data.txt
Enter fullscreen mode Exit fullscreen mode

Release Checklist (Reusable) 

[ ] Bump version
[ ] Run tests
[ ] Build sdist + wheel
[ ] twine check
[ ] Tag and push
[ ] TestPyPI upload
[ ] Fresh env install test
[ ] PyPI upload
[ ] Update README/changelog
[ ] Announce
Enter fullscreen mode Exit fullscreen mode

Useful Links

Top comments (0)