Skip to content

Latest commit

 

History

History
312 lines (227 loc) · 9.48 KB

PUBLISHING.md

File metadata and controls

312 lines (227 loc) · 9.48 KB

Publishing webamon-cli to PyPI (Windows)

The release checklist, in order. Every command here is PowerShell on Windows. Nothing is optional — each step exists because skipping it has burned a release before (see Known traps at the end).

Authentication is interactive: twine prompts for the token at upload time, so no secret is ever written to disk or into this repo.

Run everything from the project root: cd C:\Users\doyle\PycharmProjects\webamon-cli


0. Prerequisites (once per machine)

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pip install build twine

Get a PyPI API token — https://pypi.org/manage/account/token/ → Add API token, scoped to the webamon-cli project. Keep it in your password manager.

Get a separate TestPyPI token from https://test.pypi.org/manage/account/token/ (the two sites have independent accounts and tokens).

You do not need a .pypirc file. Twine will prompt for credentials on each upload, which keeps the tokens off this machine's disk. When prompted:

Enter your username: __token__
Enter your password: <paste the pypi-... token — input is hidden>

__token__ is the literal username, not your PyPI account name. The password is the whole token including the pypi- prefix. Paste with Ctrl+V or right-click; the prompt shows nothing as you type — that's expected.


1. Bump the version

The version lives in two files and they must match:

File Field
webamon_cli\__init__.py __version__ = "X.Y.Z"
pyproject.toml version = "X.Y.Z"

Everything else derives from __init__.py — the --version flag and the HTTP User-Agent. setup.py reads pyproject.toml, so there's nothing to change there.

Also update EXPECTED in tests\test_version.py to the new version.

.\.venv\Scripts\python.exe -m pytest tests/test_version.py -q

That test fails if the two files drift, or if the User-Agent falls behind.

Semver: patch = fixes, minor = new commands/options, major = breaking changes.


2. Run the full test suite

.\.venv\Scripts\python.exe -m pytest

All tests must pass. For a coverage view:

.\.venv\Scripts\python.exe -m pytest --cov=webamon_cli --cov-report=term-missing

3. Test locally as a developer (editable install)

Fast loop — source changes take effect with no reinstall:

.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\webamon.exe --version
.\.venv\Scripts\webamon.exe --help
.\.venv\Scripts\webamon.exe campaigns --help
.\.venv\Scripts\webamon.exe clusters --help

Smoke-test against the live API with a key:

$env:WEBAMON_API_KEY = "your-key-here"
.\.venv\Scripts\webamon.exe status
.\.venv\Scripts\webamon.exe clusters list --size 5
.\.venv\Scripts\webamon.exe campaigns list --size 5

An editable install proves your source works. It does not prove the built artifact works — that's step 5, and it's the step that catches packaging bugs.


4. Build the distribution

Always clean first. Stale artifacts in dist\ are the single most common way to publish the wrong thing:

Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
.\.venv\Scripts\python.exe -m build

Produces:

dist\webamon_cli-X.Y.Z-py3-none-any.whl
dist\webamon_cli-X.Y.Z.tar.gz

Confirm both carry the new version and that dist\ holds nothing else:

Get-ChildItem dist

Verify the data file shipped

webamon fields reads a bundled JSON file. If it isn't in the wheel, that command breaks for every installed user while working perfectly for you:

.\.venv\Scripts\python.exe -c "import zipfile,glob; print('\n'.join(zipfile.ZipFile(sorted(glob.glob('dist/*.whl'))[-1]).namelist()))"

webamon_cli/scans_fields.json must be in that list. It's included via MANIFEST.in (recursive-include webamon_cli *.json).

Validate the metadata

.\.venv\Scripts\python.exe -m twine check dist/*

Both files must report PASSED. This catches a malformed README that PyPI would reject — or that would render as raw text on the project page.


5. Test the built artifact in a clean venv

The most important step. Install the wheel exactly as a user would, in a venv that shares nothing with your dev environment:

$verify = "$env:TEMP\verifyvenv"
Remove-Item -Recurse -Force $verify -ErrorAction SilentlyContinue
python -m venv $verify
& "$verify\Scripts\python.exe" -m pip install (Get-ChildItem dist\*.whl).FullName

& "$verify\Scripts\webamon.exe" --version
& "$verify\Scripts\webamon.exe" --help
& "$verify\Scripts\webamon.exe" clusters --help
& "$verify\Scripts\webamon.exe" fields --search domain --format json

Checklist:

  • --version prints the version you just built (not an older one)
  • Every command group appears: campaigns, clusters, configure, fields, infostealers, report, scan, screenshot, search, status
  • fields returns JSON (proves the bundled data file shipped)
  • No ModuleNotFoundError — a dependency missing from pyproject.toml surfaces here, because the clean venv has nothing preinstalled

6. Publish to TestPyPI first

.\.venv\Scripts\python.exe -m twine upload --repository testpypi dist/*

Twine prompts:

Enter your username: __token__
Enter your password: <paste your TestPyPI token>

Install it from TestPyPI into another clean venv. --extra-index-url is required because the real dependencies (click, requests, rich) don't exist on TestPyPI:

$tp = "$env:TEMP\tpvenv"
Remove-Item -Recurse -Force $tp -ErrorAction SilentlyContinue
python -m venv $tp
& "$tp\Scripts\python.exe" -m pip install `
    --index-url https://test.pypi.org/simple/ `
    --extra-index-url https://pypi.org/simple/ `
    webamon-cli==X.Y.Z

& "$tp\Scripts\webamon.exe" --version

Also eyeball https://test.pypi.org/project/webamon-cli/ — README rendering, description, links.


7. Publish to PyPI

.\.venv\Scripts\python.exe -m twine upload dist/*

At the prompt use __token__ and your production PyPI token (not the TestPyPI one).

Then verify from real PyPI:

$final = "$env:TEMP\finalvenv"
Remove-Item -Recurse -Force $final -ErrorAction SilentlyContinue
python -m venv $final
& "$final\Scripts\python.exe" -m pip install webamon-cli==X.Y.Z
& "$final\Scripts\webamon.exe" --version

A version number on PyPI can never be reused. Even after deleting a release, that version is burned forever. If you publish a broken 0.3.0, the only fix is to publish 0.3.1. That's why steps 5 and 6 exist.


8. Tag the release

git add -A
git commit -m "Release vX.Y.Z"
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push
git push --tags

Release checklist (copy into the PR/issue)

[ ] Version bumped in webamon_cli\__init__.py AND pyproject.toml
[ ] EXPECTED updated in tests\test_version.py
[ ] Full test suite passes
[ ] Remove-Item -Recurse -Force dist, build, *.egg-info
[ ] python -m build
[ ] Get-ChildItem dist  -> new version only, nothing stale
[ ] scans_fields.json present in the wheel
[ ] twine check dist/*  -> PASSED
[ ] Clean-venv install of the wheel: --version correct, all commands present
[ ] TestPyPI upload + clean install verified
[ ] twine upload dist/*  (interactive: __token__ + production token)
[ ] Verified from real PyPI
[ ] Tagged and pushed

Known traps

Stale wheels in dist\. During 0.3.0 development a rebuild produced a wheel with the same version as one already in dist\. pip installed the stale file and the new campaigns command was silently missing from the "verified" install. Always clean before building, and always confirm --version in the clean venv.

A version bump in only one file. __init__.py and pyproject.toml are independent. If they disagree, the wheel metadata and --version disagree too. tests\test_version.py guards this — run it.

Hardcoded version strings. The User-Agent sat at 0.1.1 while the package was 0.2.3, so API logs mislabelled every request for two releases. It now derives from __version__; keep it that way.

Editable install passing while the wheel fails. pip install -e . uses your source tree directly, so it can't catch a missing package-data file or an unlisted dependency. Only the clean-venv wheel test does.

Missing runtime dependency. Anything imported at runtime must be in pyproject.toml's dependencies. Your dev venv has extras installed; the clean venv is what proves the list is complete.

PowerShell gotchas.

  • Use the backtick ` for line continuation, not \.
  • .\.venv\Scripts\python.exe — the leading .\ is required to run from the current directory.
  • Use & to invoke an executable held in a variable: & "$verify\Scripts\webamon.exe" --version.
  • Remove-Item -Recurse -Force is the rm -rf equivalent; -ErrorAction SilentlyContinue stops it erroring when the path is absent.

If you ever do want stored credentials instead of the interactive prompt, the file is C:\Users\<you>\.pypirc (twine finds it automatically) and it must contain a [distutils] block listing the servers. Lock it down with icacls "$env:USERPROFILE\.pypirc" /inheritance:r /grant:r "$env:USERNAME:(R,W)". The interactive prompt is preferred — a release happens a few times a year, and nothing lands on disk.