Python Academy · Lesson

Versioning and Metadata

Manage package metadata.

Versioning and Metadata is a free Python Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Python Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Metadata Matters

Metadata is everything about your package except the code: its version, description, license, author, and links. PyPI uses it to display your project, and pip uses it to resolve dependencies.

Good metadata makes your package trustworthy and installable.

Semantic Versioning

The convention is MAJOR.MINOR.PATCH:

MAJOR breaking changes
MINOR new, backward-compatible features
PATCH backward-compatible bug fixes

Users rely on this to know whether an upgrade is safe.

version = '2.4.1'
major, minor, patch = version.split('.')
print('Major', major, 'Minor', minor, 'Patch', patch)
print('Bug fix -> bump patch to', major + '.' + minor + '.' + str(int(patch) + 1))

Choosing the Next Version

Deciding the bump is rule-based: did you break the API, add a feature, or just fix a bug? Encoding the rule makes releases consistent.

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.split('.'))
    if kind == 'major':
        return str(major + 1) + '.0.0'
    if kind == 'minor':
        return str(major) + '.' + str(minor + 1) + '.0'
    return str(major) + '.' + str(minor) + '.' + str(patch + 1)

print(bump('1.2.3', 'minor'))
print(bump('1.2.3', 'major'))

Pre-release and Dev Versions

Python allows suffixes: 1.0.0a1 (alpha), 1.0.0b2 (beta), 1.0.0rc1 (release candidate), and 1.0.0.dev3. pip treats these as earlier than the final 1.0.0, so testers can opt in without affecting normal users.

Single Source of Truth

Keep the version in exactly one place. Either declare it statically in pyproject.toml, or mark it dynamic and read it from the code (or a tag) via tools like setuptools-scm. Two copies inevitably drift apart.

Description and README

A short description appears in search results. The long description comes from your readme (usually README.md) and renders as the PyPI project page. Point to it with readme = 'README.md'.

A clear README is your best marketing.

License

popular = ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'GPL-3.0-only']
for lic in popular:
    print('SPDX:', lic)

Classifiers

classifiers are standardized tags from PyPI's list, such as 'Programming Language :: Python :: 3.11' or 'Development Status :: 4 - Beta'. They power PyPI's filters and signal maturity and supported versions.

Project URLs

Under [project.urls] add links like Homepage, Documentation, Source, and Changelog. These appear in a sidebar on PyPI and help users find your repo and docs.

urls = {
    'Homepage': 'https://example.com',
    'Source': 'https://github.com/me/mytool',
    'Issues': 'https://github.com/me/mytool/issues',
}
for label, link in urls.items():
    print(label.ljust(10), link)

Keywords for Discovery

The keywords field is a list of short terms that help users find your package in searches. Choose words people would actually type, like ['cli', 'automation', 'excel'], rather than generic filler.

Together with classifiers, keywords improve how discoverable your project is.

A Changelog

Maintain a CHANGELOG that records what changed in each version. Users read it before upgrading to learn about new features and breaking changes. Linking it under [project.urls] makes it one click from the PyPI page.

A good changelog turns a version number into a story users can follow.

Quick Check

Test your versioning knowledge.

Recap

You managed package metadata:

Semantic versioning MAJOR.MINOR.PATCH, plus pre-release suffixes
Keep the version in a single source of truth
Provide description, a README long description, and a license
Add classifiers and [project.urls] so PyPI displays your project well

Frequently asked questions

Is the “Versioning and Metadata” lesson free?

Yes — the full text of “Versioning and Metadata” is free to read here on the web, and the Python Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Python Academy course, upgrade to CoddyKit PRO.

What will I learn in “Versioning and Metadata”?

Manage package metadata. You practise Python Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Python Academy?

No prior experience is required. Python Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Versioning and Metadata” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Python Academy lesson?

Yes. Every Python Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Python Academy