Merge pull request #10460 from jefferyto/python-readme-update

python: Readme updates

1 files changed, 34 insertions, 24 deletions

diff --git a/lang/python/README.md b/lang/python/README.md
index 61325b7d5..94b2afaf6 100644
--- a/lang/python/README.md
+++ b/lang/python/README.md
@@ -171,48 +171,58 @@ This section will describe both, and then it can be inferred which is for which.
 
 Packaging for both Python & Python3 uses the `VARIANT` mechanism for packaging inside OpenWrt. (#### FIXME: find a link for this later if it exists)
 
-### PKG_BUILD_DIR
-
-It's important when packaging for both Python & Python3 to override this variable, so that the build directory differs for each variant.
+### Include python[3]-package.mk
 
-Typically it's just something like:
+If packaging for Python, add this after  `include $(INCLUDE_DIR)/package.mk`
 ```
-PKG_BUILD_DIR:=$(BUILD_DIR)/$(BUILD_VARIANT)-pyasn1-$(PKG_VERSION)
+include ../python-package.mk
 ```
-Where `pyasn1` should be some other name, or maybe `PKG_NAME`
 
-This should be added before this include:
+If packaging for Python3, add this after  `include $(INCLUDE_DIR)/package.mk`
 ```
-include $(INCLUDE_DIR)/package.mk
+include ../python3-package.mk
 ```
 
-### PKG_UNPACK
+Order doesn't matter between `python-package.mk` & `python3-package.mk`.
 
-In many cases, this needs to be overriden. This is usually because the way Python packages are archived, don't follow the convention of other `tar.gz` packages.
+These will make sure that build rules for Python or Python3 can be specified and picked up for build.
+
+### Include pypi.mk (optional)
+
+If the package source code will be downloaded from [pypi.org](https://pypi.org/), including `pypi.mk` can help simplify the package Makefile.
 
-So, something like:
+To use `pypi.mk`, add this **before** `include $(INCLUDE_DIR)/package.mk`:
 ```
-PKG_UNPACK=$(HOST_TAR) -C $(PKG_BUILD_DIR) --strip-components=1 -xzf $(DL_DIR)/$(PKG_SOURCE)
+include ../pypi.mk
 ```
-should be added.
 
-It's not important whether this is after or before `include $(INCLUDE_DIR)/package.mk`
+`pypi.mk` has several `PYPI_*` variables that must/can be set (see below); these should be set before `pypi.mk` is included, i.e. before the `include ../pypi.mk` line.
 
-### Include python[3]-package.mk
+`pypi.mk` also provides default values for `PKG_SOURCE` and `PKG_SOURCE_URL`, so these variables may be omitted.
 
-If packaging for Python, add this after  `include $(INCLUDE_DIR)/package.mk`
-```
-include ../python-package.mk
-```
+One variable is required:
 
-If packaging for Python3, add this after  `include $(INCLUDE_DIR)/package.mk`
+* `PYPI_NAME`: Package name on pypi.org. This should match the PyPI name exactly.
+
+  For example (from the `python-yaml` package):
+  ```
+  PYPI_NAME:=PyYAML
+  ```
+
+These variables are optional:
+
+* `PYPI_SOURCE_NAME`: Package name component of the source tarball filename  
+  Default: Same value as `PYPI_NAME`
+
+* `PYPI_SOURCE_EXT`: File extension of the source tarball filename  
+  Default: `tar.gz`
+
+`pypi.mk` constructs the default `PKG_SOURCE` value from these variables (and `PKG_VERSION`):
 ```
-include ../python3-package.mk
+PKG_SOURCE?=$(PYPI_SOURCE_NAME)-$(PKG_VERSION).$(PYPI_SOURCE_EXT)
 ```
 
-Order doesn't matter between `python-package.mk` & `python3-package.mk`.
-
-These will make sure that build rules for Python or Python3 can be specified and picked up for build.
+The `PYPI_SOURCE_*` variables allow this default `PKG_SOURCE` value to be customized as necessary.
 
 ### Add Package/<PKG_NAME> OpenWrt definitions