Python Ports Policy

Status: Defacto. If in doubt, check with the FreeBSD Python Team

This policy document is used:

Upstream Branch Support

FreeBSD currently supports Python (CPython) branches until they are end-of-life (EoL) as defined upstream.

Note: Upstream currently only provides bug fixes for the latest minor release (and Python 2.7 at the time of this writing). In order to reduce maintenance overheads and inconsistencies between ports, it is likely that the FreeBSD Python team will modify its branch support policy to only support branches that are also supported by upstream in the future.

Naming

Prefixing (py-*)

Guideline: Prefix all ports unless Python version is entirely irrelevant.

PORTNAME

Guideline: Match port names to upstream names exactly.

IMPORTANT

Check if a package is registered in PyPI (CHEESESHOP), even when using alternate code sources.

PKGNAMEPREFIX

Guideline: Prefix all ports unless Python version is entirely irrelevant.

Metadata

CATEGORIES

Guideline: Always include python category unless use of Python is entirely irrelevant.

COMMENT

Guideline: Match upstream metadata as completely and closely as possible.

MASTER_SITES

Guideline: Use standard Python ecosystem infrastructure whenever possible.

Examples where temporarily using an alternate MASTER_SITES is warranted:

In these cases, issues or pull request SHOULD be created upstream to rectify the problem, and MASTER_SITES switched to CHEESESHOP when the change is released in a later version.

This ensures upstreams packaging and deployment pipeline is well tested and standardised (Python standards), as it is heavily relied upon (setuptools, autoplist, documentation, discoverability, etc).

USES=python

Guideline: Python ports are declarative ("this supports x,y,z", not imperative ("install/use x,y,z"). Guideline: Match upstream metadata as completely and closely as possible.

USE_PYTHON Features

Guideline: Use all standard Python ecosystem infrastructure whenever possible.

autoplist

Note: autoplist can be used in combination with PLIST_FILES, PLIST_DIRS and explicit entries in pkg-plist

concurrent

See Also: https://reviews.freebsd.org/D20927#454268

distutils

Dependencies

Guideline: Match upstream metadata as completely and closely as possible.

IMPORTANT:

Be careful when referencing dependencies only from requirements.txt files. Unless the setup.py parses those requirements.txt entries, only setup.py defined dependencies are canonical/actual.

Be careful, dependencies are often declared inconsistently, incompletely or in multiple places (Eg: requirements.txt, test_requirements, tox.ini)

Modifying Dependencies

Optional Dependencies

Optional / Transitive Dependencies

Tests

Guideline: Ports should be testable unless they cannot be.

Patches

Guideline: Document downstream patches & changes that diverge from upstream.

Upstreaming

Guideline: Upstream is a first priority.

Framework Compliance

Packages and Modules

Python as a Build Dependency

This allows ports to be built with different default versions of Python.

Python Scripts

Example:

A port devel/foobar provides a script foofoo.py, which requires textproc/py-barbar at runtime

Python Language Ports and Framework

Description: Upstream issue summary or commit short log
Issue ID: URL to upstream Issue
Changeset: URL to upstream Commit
TODO: Comments on what needs to be done to remove local patch

TODO


CategoryPorts

Python/PortsPolicy (last edited 2021-08-25T01:35:47+0000 by KubilayKocak)