python:portspolicy

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
python:portspolicy [2020/08/09 02:54] – Fix typoe: tests_require not tests_requires KubilayKocakpython:portspolicy [2023/03/02 02:17] (current) – emphasise case-sensitivity CharlieLi
Line 7: Line 7:
   * As a reference to a well-defined target-state   * As a reference to a well-defined target-state
   * To inform discussions and technical implementations   * To inform discussions and technical implementations
-  * To provide %%FreeBSD%% tesPython Users and Organisations with insight into the Python@ team goals+  * To provide %%FreeBSD%% Python Users and Organisations with insight into the Python@ team goals
   * To orient and focus resources towards common initiatives or goals.   * To orient and focus resources towards common initiatives or goals.
  
Line 20: Line 20:
 ===== Naming ===== ===== Naming =====
  
-==== General ====+==== Prefixing (py-*) ====
  
-  * Subversion directory name MUST be lowercase(''%%py-PORTNAME%%'')+**Guideline**: Prefix all ports unless Python version is entirely irrelevant.
  
-==== Prefixing (py-*) ====+  * Port directory name MUST be lowercase(''%%py-PORTNAME%%'')
  
   * Python ports MUST be prefixed with ''%%py-%%'', named ''%%category/py-<PORTNAME>%%'', unless there is a compelling case not to.   * Python ports MUST be prefixed with ''%%py-%%'', named ''%%category/py-<PORTNAME>%%'', unless there is a compelling case not to.
-    * Compelling cases do NOT include: +    * Compelling cases do NOT include:
       * [[Python/PyPI|PyPi]] name or PORTNAME already contains ''%%py%%'', ''%%python%%'', ''%%python-*%%''  or similar prefix or suffix       * [[Python/PyPI|PyPi]] name or PORTNAME already contains ''%%py%%'', ''%%python%%'', ''%%python-*%%''  or similar prefix or suffix
       * Package is not listed in %%PyPI%%       * Package is not listed in %%PyPI%%
Line 34: Line 34:
  
 ==== PORTNAME ==== ==== PORTNAME ====
 +
 +**Guideline**: Match port names to upstream names exactly.
  
 //IMPORTANT// //IMPORTANT//
Line 39: Line 41:
 Check if a package is registered in %%PyPI%% (CHEESESHOP), even when using alternate code sources. Check if a package is registered in %%PyPI%% (CHEESESHOP), even when using alternate code sources.
  
-  * ''%%PORTNAME%%'' MUST be lowercase(PORTNAME) +  * If the package is registered on %%PyPI%% 
-  * ''%%PORTNAME%%'' MUST **exactly** match the //upstream name//. +    * ''%%PORTNAME%%'' MUST **exactly** match the registered %%PyPI%% package name, **including casing**. 
-  * ''%%PORTNAME%%'' MUST **exactly** match the registered %%PyPI%% package name, if the package is registered on %%PyPI%% +    * The %%PyPI%% package name is that which is displayed in the URL at [[https://pypi.org/]]%%<%%package-name>
- +
-    * The %%PyPI%% package name is that which is displayed and in the URL at [[https://pypi.org/]]%%<%%package-name>+
     * Note: The displayed %%PyPI%% package name can be different than the package name specified in ''%%setup.py:name%%''     * Note: The displayed %%PyPI%% package name can be different than the package name specified in ''%%setup.py:name%%''
- +  * If the package is **NOT** registered on %%PyPI%%: 
-    * Ports MUST NOT modify the name if it already contains ''%%py%%'', ''%%python%%'', ''%%python-*%%''  or similar prefix or suffix +    * ''%%PORTNAME%%'' MUST **exactly** match ''%%setup.py:name%%'' value. 
-    * Ports MUST include all non-alpha numeric characters in the name (such as dashes (-%%))%% +  * Ports MUST NOT modify the name if it already contains ''%%py%%'', ''%%python%%'', ''%%python-*%%''  or similar prefix or suffix 
 +  * Ports MUST include all non-alpha numeric characters in the name (such as dashes (-%%))%%
     * This also applies if %%PyPi%% (CHEESESHOP) is NOT used for ''%%MASTER_SITES%%'' or ''%%DISTFILES%%''. Example: ''%%USE_GITHUB=yes%%''     * This also applies if %%PyPi%% (CHEESESHOP) is NOT used for ''%%MASTER_SITES%%'' or ''%%DISTFILES%%''. Example: ''%%USE_GITHUB=yes%%''
  
 ==== PKGNAMEPREFIX ==== ==== PKGNAMEPREFIX ====
 +
 +**Guideline**: Prefix all ports unless Python version is entirely irrelevant.
  
   * Ports MUST use ''%%PKGNAMEPREFIX%%'', unless there is a compelling case not to.   * Ports MUST use ''%%PKGNAMEPREFIX%%'', unless there is a compelling case not to.
   * ''%%PKGNAMEPREFIX%%'' MUST be set to ''%%${PYTHON_PKGNAMEPREFIX}%%''   * ''%%PKGNAMEPREFIX%%'' MUST be set to ''%%${PYTHON_PKGNAMEPREFIX}%%''
  
-===== CATEGORIES =====+===== Metadata ===== 
 + 
 +==== CATEGORIES ==== 
 + 
 +**Guideline**: Always include python category unless use of Python is entirely irrelevant.
  
   * Ports MUST add ''%%python%%'' as a secondary category, unless there is a compelling reason not to.   * Ports MUST add ''%%python%%'' as a secondary category, unless there is a compelling reason not to.
   * Ports SHOULD add multiple ''%%CATEGORIES%%'' as needed to aid discovery by users.   * Ports SHOULD add multiple ''%%CATEGORIES%%'' as needed to aid discovery by users.
 +
 +==== COMMENT ====
 +
 +**Guideline**: Match upstream metadata as completely and closely as possible.
 +
 +  * Ports SHOULD match the upstream short description or summary where possible, modulo requirements and changes for portlint compliance
 +    * For Python ports, this almost always means what is defined in ''%%setup.py:description%%''
  
 ===== MASTER_SITES ===== ===== MASTER_SITES =====
  
-Ports SHOULD use ''%%MASTER_SITES=CHEESESHOP%%'' if a Python package is registered on %%PyPI%%, unless there is a compelling (temporary) case not to.+**Guideline**: Use standard Python ecosystem infrastructure whenever possible. 
 + 
 +  * Ports SHOULD use ''%%MASTER_SITES=CHEESESHOP%%'' if a Python package is registered on %%PyPI%%, unless there is a compelling (temporary) case not to.
  
-Examples where temporarily using an alternate MASTER_SITES is OK:+Examples where temporarily using an alternate MASTER_SITES is warranted:
  
-  * Certain files are not correctly packaged/included in the %%PyPI%% sdist, such as test suite files or data. Submit an upstream issue or PR in these cases. +  * Some files are not correctly packaged or included at all in the %%PyPI%% sdist, such as licenses, test suite files or data. Submit an upstream issue or PR in these cases. 
-  * A source distribution (sdist, aka tarball) has not been uploaded yet.+  * A source distribution (sdist) has not been uploaded yet
  
 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. 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.
Line 76: Line 91:
  
 ===== USES=python ===== ===== 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.
  
   * Python ports MUST declare USES=python ''%%:<version-spec>%%'' as completely and accurately as possible, without being incorrect, given existing syntax constraints.   * Python ports MUST declare USES=python ''%%:<version-spec>%%'' as completely and accurately as possible, without being incorrect, given existing syntax constraints.
Line 83: Line 101:
  
 ===== USE_PYTHON Features ===== ===== USE_PYTHON Features =====
 +
 +**Guideline**: Use all standard Python ecosystem infrastructure whenever possible.
 +
 +==== pep517 ====
 +
 +  * Packages following PEP-517 (have a pyproject.toml specifying a build backend that builds an installable wheel) SHALL use pep517, unless there is a compelling reason not to.
 +
 +==== distutils ====
 +
 +  * Packages that use distutils (directly executes a setup.py, import distutils/setuptools), SHOULD use distutils, unless there is a compelling reason not to.
  
 ==== autoplist ==== ==== autoplist ====
  
 +  * Packages following PEP-517 (have a pyproject.toml specifying a build backend that builds an installable wheel) and built as such SHALL use autoplist.
   * Packages that use distutils (have a setup.py, import distutils/setuptools), SHOULD use autoplist, unless there is a compelling reason not to.   * Packages that use distutils (have a setup.py, import distutils/setuptools), SHOULD use autoplist, unless there is a compelling reason not to.
  
Line 97: Line 126:
  
 See Also: https://reviews.freebsd.org/D20927#454268 See Also: https://reviews.freebsd.org/D20927#454268
- 
-==== distutils ==== 
- 
-  * Packages that use distutils (have a setup.py, import distutils/setuptools), SHOULD use distutils, unless there is a compelling reason not to. 
  
 ===== Dependencies ===== ===== Dependencies =====
 +
 +**Guideline**: Match upstream metadata as completely and closely as possible.
  
 **IMPORTANT**: **IMPORTANT**:
Line 117: Line 144:
     * Port maintainers SHOULD fix missing or incorrectly specified dependencies, in the port, AND [[Python/PortsPolicy#Upstream|upstream]] the changes.     * Port maintainers SHOULD fix missing or incorrectly specified dependencies, in the port, AND [[Python/PortsPolicy#Upstream|upstream]] the changes.
     * Use common sense for upstream version requirements that set //maximum versions// or pin //very specific// versions, eg: ''%%==%%'', ''%%<=%%'', ''%%<%%''     * Use common sense for upstream version requirements that set //maximum versions// or pin //very specific// versions, eg: ''%%==%%'', ''%%<=%%'', ''%%<%%''
 +      * **IMPORTANT**: Common sense does not create an exception to the //exactly matching dependencies// requirement above.
  
 ==== Modifying Dependencies ==== ==== Modifying Dependencies ====
Line 122: Line 150:
   * Ports MAY patch dependencies in the upstream sources (WRKSRC), if they need to be added, modified or removed.   * Ports MAY patch dependencies in the upstream sources (WRKSRC), if they need to be added, modified or removed.
     * When patching dependencies, changes MUST be verified to work correctly, ideally via the upstream test suite.     * When patching dependencies, changes MUST be verified to work correctly, ideally via the upstream test suite.
-    * Example: Changing ''%%==%%'' (pinned) dependencies to ''%%>=%%'' or removing maximum version ''%%<X.Y%%'' version specifiers.   +    * Example: Changing ''%%==%%'' (pinned) dependencies to ''%%>=%%'' or removing maximum version ''%%<X.Y%%'' version specifiers.
  
 ==== Optional Dependencies ==== ==== Optional Dependencies ====
Line 130: Line 158:
   * Port OPTIONS for optional functionality, SHOULD be enabled by default (defined in OPTIONS_DEFAULT).   * Port OPTIONS for optional functionality, SHOULD be enabled by default (defined in OPTIONS_DEFAULT).
  
-==== Transitive Dependencies ====+==== Optional / Transitive Dependencies ====
  
   * If a package depends on another packages **optional** dependencies, the package MUST depend on those dependencies directly/explicitly.   * If a package depends on another packages **optional** dependencies, the package MUST depend on those dependencies directly/explicitly.
-    * Eg: Package A depends on %%PackageB%%[optional] (defined in extras_require). Package A should depend explicitly on all dependencies listed in Package B's %%%%''%%extras_require{ optional: ..., ...}%%''%%%% list.+    * Example: Package A depends on %%PackageB%%[optional] (defined in extras_require). Package A should depend explicitly on all dependencies listed in Package B's %%%%''%%extras_require{ optional: ..., ...}%%''%%%% list.
  
 ===== Tests ===== ===== Tests =====
 +
 +**Guideline**: Ports should be testable unless they cannot be.
  
   * Python ports SHOULD include a ''%%do-test%%'' target if the package includes tests.   * Python ports SHOULD include a ''%%do-test%%'' target if the package includes tests.
 +    * Example: ''%% @(cd ${TEST_WRKSRC} && ${SETENV} ${TEST_ENV} ${PYTHON_CMD} ${PYDISTUTILS_SETUP} test)%%''
   * Python ports SHOULD add ''%%TEST_DEPENDS%%'' referring to the package ''%%tests_require%%'' dependencies.   * Python ports SHOULD add ''%%TEST_DEPENDS%%'' referring to the package ''%%tests_require%%'' dependencies.
  
 ===== Patches ===== ===== Patches =====
 +
 +**Guideline**: Document downstream patches & changes that diverge from upstream.
  
   * Python ports SHOULD [[Python/PortsPolicy#Breadcrumb_Format|document their patches]]   * Python ports SHOULD [[Python/PortsPolicy#Breadcrumb_Format|document their patches]]
Line 147: Line 180:
  
 ===== Upstreaming ===== ===== Upstreaming =====
 +
 +**Guideline**: Upstream is a first priority.
  
   * Python port maintainers SHOULD (strongly encouraged) aim to:   * Python port maintainers SHOULD (strongly encouraged) aim to:
Line 161: Line 196:
 ==== Packages and Modules ==== ==== Packages and Modules ====
  
-  * Ports that install Python modules or packages (anything going into ''%%${PYTHON_SITELIBDIR}%%''), MUST use ''%%${PYTHON_CMD}%%'' at build and installation time, not python, python2 or python3. +  * Ports that install Python modules or packages (anything going into ''%%${PYTHON_SITELIBDIR}%%''), MUST use ''%%${PYTHON_CMD}%%'' at build and installation time, not python, python2 or python3.
   * Executable scripts being installed MUST use ''%%${PYTHON_CMD}%%'' as shebang line. See: ''%%Mk/Uses/shebangfix.mk%%''   * Executable scripts being installed MUST use ''%%${PYTHON_CMD}%%'' as shebang line. See: ''%%Mk/Uses/shebangfix.mk%%''
  
Line 167: Line 202:
  
   * Ports depending on Python to build MUST use''%%${PYTHON_CMD}%%'' for the build system/command invocation.   * Ports depending on Python to build MUST use''%%${PYTHON_CMD}%%'' for the build system/command invocation.
-  * Ports MUST NOT use version-unspecific Python invocations such as ''%%python%%'', ''%%python2%%'' or ''%%python3%%''. +  * Ports MUST NOT use version-unspecific Python invocations such as ''%%python%%'', ''%%python2%%'' or ''%%python3%%''.
  
 This allows ports to be built with different default versions of Python. This allows ports to be built with different default versions of Python.
  • python/portspolicy.1596941678.txt.gz
  • Last modified: 2020/08/09 02:54
  • by KubilayKocak