🔒 Shipping 1.0.0: From Local Repo to a Published Python Package

Shipping 1.0.0: From Local Repo to a Published Python Package

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 t…

Sichere Programmierung dev.to 25.11.2025, 00:48 Uhr 3 Min. Lesezeit

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

Build backend: setuptools (standard pyproject.toml)

Build helper: build

Upload tool: twine

Staging registry: TestPyPI (https://test.pypi.org)

Production registry: PyPI (https://pypi.org)

Release Workflow (Detailed)

Clean repo

   git status

Update version in pyproject.toml (set to 1.0.0).

Run tests

   python -m pytest

(Optional) Add or confirm __all__ exports and __init__.py.

Build distributions

   python -m pip install --upgrade build twine

   python -m build

   ls dist/

Validate artifacts

   python -m twine check dist/*

Tag release

   git tag -a v1.0.0 -m "Release 1.0.0"

   git push origin v1.0.0

Upload to TestPyPI

   python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

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__)"

Upload to PyPI
```
python -m twine upload dist/*
```

Update README: add install, usage, changelog section.

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 = "[email protected]" }

]

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"]

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

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

TestPyPI (staging validation):

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

Upgrade:

python -m pip install -U your-package-name

Uninstall:

python -m pip uninstall your-package-name

Quick Start

from your_package import main_tool



result = main_tool("input text")

print(result)

CLI example (if provided):

your-package-name --help

your-package-name run --input data.txt

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