From d06f049ef2b0a75e62550143f9af3ff8144a6f46 Mon Sep 17 00:00:00 2001 From: Laurent Mazuel Date: Thu, 11 Nov 2021 09:57:54 -0800 Subject: [PATCH 1/7] Update packaging.md --- doc/dev/packaging.md | 49 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index 861840f32656..f1092d7745f4 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -1,26 +1,25 @@ # Azure packaging -This article describes how to declare setup.py and all packaging information for packages inside the `azure` namespace +This article describes the recommendation on how to define namespace packaging to release a package inside the `azure` namespace. Being inside the `azure` namespace meaning you have a service `myservice` that you want to import using: +```python +import azure.myservice +``` Namespace packaging is complicated in Python, here's a few reading if you still doubt it: - https://packaging.python.org/guides/packaging-namespace-packages/ - https://www.python.org/dev/peps/pep-0420/ - https://github.com/pypa/sample-namespace-packages -This article describes the recommendation on how to define namespace packaging to release a package inside the `azure` namespace. Being inside the `azure` namespace meaning you have a service `myservice` that you want to import using: -```python -import azure.myservice -``` - Note: -- This article is not about setup.py or setup.cfg or the right way to *write* the packaging, it's about what instructions you should use to achieve this. If you are fluent in setuptools, and prefer to write the suggestions in setup.cfg and not in setup.py, this is not a concern. +While this article provides example using setup.py, there is no problem with achieving it with setup.cfg or other methods, as long as the constraints on the final wheels/sdist are met. + +*This page has been updated to be Python 3 only packages as we do not recommend to support Python 2 after January 1st 2022.* If you still want to support Python 2 for some reasons, there is a section at the bottom with some details (or you have the Github history, to read the page as it was on November 1st 2021). # What are the constraints? We want to build sdist and wheels in order to follow the following constraints: - Solution should work with *recent* versions of pip and setuptools (not the very latest only, but not archaeology either) -- Wheels must work with Python 2.7 and 3.6+ -- easy-install scenario is a plus, but cannot be considered critical anymore +- Wheels must work with Python 3.6+ - mixed dev installation and PyPI installation should be explicitly addressed # What do I do in my files to achieve that @@ -55,13 +54,9 @@ The "packages" section MUST EXCLUDE the `azure` package. Example: ]), ``` -The "extras_requires" section MUST include a conditional dependency on "azure-nspkg" for Python 2. There is also a conditional dependency on "typing" for Python 3.5 because of the type-hinting for Python 3.5 and above. Example: - +Since the package is Python 3 only, you must notify it in the setup.py as well: ```python - extras_require={ - ":python_version<'3.0'": ['azure-nspkg'], - ":python_version<'3.5'": ['typing'], - } + python_requires=">=3.6", ``` Example of a full setup.py @@ -113,16 +108,15 @@ setup( classifiers=[ 'Development Status :: 4 - Beta', 'Programming Language :: Python', - 'Programming Language :: Python :: 2', - 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.5', 'Programming Language :: Python :: 3.6', 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', 'License :: OSI Approved :: MIT License', ], + python_requires=">=3.6", zip_safe=False, packages=find_packages(exclude=[ 'tests', @@ -134,17 +128,24 @@ setup( 'msrestazure>=0.4.32,<2.0.0', 'azure-common~=1.1', ], - extras_require={ - ":python_version<'3.0'": ['azure-nspkg'], - ":python_version<'3.5'": ['typing'], - } ) ``` -This syntax works with setuptools >= 17.1 and pip >= 6.0, which is considered enough to support in 2019. +This syntax works with setuptools >= 24.2.0 (July 2016) and pip >= 9.0 (Nov 2016), which is considered enough to support in 2021. # How can I check if my packages are built correctly? - wheels must NOT contain a `azure/__init__.py` file (you can open it with a zip util to check) -- wheels installs `azure-nskpg` ONLY on Python 2. - sdist must contain a `azure/__init__.py` file that declares `azure` as a namespace package using the `pkgutil` syntax + +# Note on Python 2 + +The "extras_requires" section MUST include a conditional dependency on "azure-nspkg" for Python 2. Example: + +```python + extras_require={ + ":python_version<'3.0'": ['azure-nspkg'], + } +``` + +An additional verification is that wheels installs `azure-nskpg` ONLY on Python 2. From 814fbc49f69bced326f7128f4d09af25d27530ad Mon Sep 17 00:00:00 2001 From: Laurent Mazuel Date: Thu, 11 Nov 2021 10:03:09 -0800 Subject: [PATCH 2/7] 3.7 as minimal --- doc/dev/packaging.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index f1092d7745f4..9aa18fb3881e 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -19,7 +19,7 @@ While this article provides example using setup.py, there is no problem with ach We want to build sdist and wheels in order to follow the following constraints: - Solution should work with *recent* versions of pip and setuptools (not the very latest only, but not archaeology either) -- Wheels must work with Python 3.6+ +- Wheels must work with Python 3.7+ - mixed dev installation and PyPI installation should be explicitly addressed # What do I do in my files to achieve that @@ -56,7 +56,7 @@ The "packages" section MUST EXCLUDE the `azure` package. Example: Since the package is Python 3 only, you must notify it in the setup.py as well: ```python - python_requires=">=3.6", + python_requires=">=3.7", ``` Example of a full setup.py @@ -109,14 +109,13 @@ setup( 'Development Status :: 4 - Beta', 'Programming Language :: Python', 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.6', 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', 'License :: OSI Approved :: MIT License', ], - python_requires=">=3.6", + python_requires=">=3.7", zip_safe=False, packages=find_packages(exclude=[ 'tests', From 59c5cc754c48c1245c0e81cefe9cbddb34fb1b06 Mon Sep 17 00:00:00 2001 From: Laurent Mazuel Date: Thu, 11 Nov 2021 13:28:41 -0800 Subject: [PATCH 3/7] Stop checking if azure 0.x is installed --- doc/dev/packaging.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index 9aa18fb3881e..3a7dbfa5418f 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -137,6 +137,28 @@ This syntax works with setuptools >= 24.2.0 (July 2016) and pip >= 9.0 (Nov 2016 - wheels must NOT contain a `azure/__init__.py` file (you can open it with a zip util to check) - sdist must contain a `azure/__init__.py` file that declares `azure` as a namespace package using the `pkgutil` syntax +# Note on checking old Azure packages + +You may see code looking like this: +```python +# azure v0.x is not compatible with this package +# azure v0.x used to have a __version__ attribute (newer versions don't) +try: + import azure + + try: + VER = azure.__version__ # type: ignore + raise Exception( + "This package is incompatible with azure=={}. ".format(VER) + 'Uninstall it with "pip uninstall azure".' + ) + except AttributeError: + pass +except ImportError: + pass +``` + +This was to prevent some difficult update scenario 6 years ago, and can be safely removed from your setup.py + # Note on Python 2 The "extras_requires" section MUST include a conditional dependency on "azure-nspkg" for Python 2. Example: From 75676734a3298418bdf489bb68e277ffad363d0d Mon Sep 17 00:00:00 2001 From: Laurent Mazuel Date: Thu, 11 Nov 2021 13:31:38 -0800 Subject: [PATCH 4/7] TLDR version --- doc/dev/packaging.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index 3a7dbfa5418f..b1fac910f615 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -137,6 +137,13 @@ This syntax works with setuptools >= 24.2.0 (July 2016) and pip >= 9.0 (Nov 2016 - wheels must NOT contain a `azure/__init__.py` file (you can open it with a zip util to check) - sdist must contain a `azure/__init__.py` file that declares `azure` as a namespace package using the `pkgutil` syntax +# I already have a package thatn supports Python 2, can I get short version on how to udpate to Python 3 + +- Remove `extra_requires` +- Add `python_requires=">=3.7",` +- Remove the Python 2 and 3.5/3.6 classifiers +- Remove the "azure" check if applicable (see next note) + # Note on checking old Azure packages You may see code looking like this: From 9cd3a51e0a66e551fe7f1924fdc16d3ddd219c06 Mon Sep 17 00:00:00 2001 From: Laurent Mazuel Date: Thu, 11 Nov 2021 13:40:20 -0800 Subject: [PATCH 5/7] Not universal anymore --- doc/dev/packaging.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index b1fac910f615..ec4854fb2a4b 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -132,17 +132,22 @@ setup( This syntax works with setuptools >= 24.2.0 (July 2016) and pip >= 9.0 (Nov 2016), which is considered enough to support in 2021. +Since the package is Python 3 only, do NOT make this wheel universal. This usually means you should NOT have `universal=1` in the `setup.cfg`. It may mean you can completely remove the file if `universal` was the only configuration option inside. + # How can I check if my packages are built correctly? -- wheels must NOT contain a `azure/__init__.py` file (you can open it with a zip util to check) +- wheel file must NOT contain a `azure/__init__.py` file (you can open it with a zip util to check) +- wheel file name finishes with `py3-none-any`, and NOT by `py2.py3-none-any`. - sdist must contain a `azure/__init__.py` file that declares `azure` as a namespace package using the `pkgutil` syntax -# I already have a package thatn supports Python 2, can I get short version on how to udpate to Python 3 +# I already have a package that supports Python 2, can I get short version on how to udpate to Python 3 only? -- Remove `extra_requires` -- Add `python_requires=">=3.7",` -- Remove the Python 2 and 3.5/3.6 classifiers -- Remove the "azure" check if applicable (see next note) +- Remove "universal" from setup.cfg, or remove completly the file if it was the only option +- In setup.py: + - Remove `extra_requires` + - Add `python_requires=">=3.7",` + - Remove the Python 2 and 3.5/3.6 classifiers + - Remove the "azure" check if applicable (see next note) # Note on checking old Azure packages From 6a35cb496d549ecaf0c8c7961a62e2357e6ecfac Mon Sep 17 00:00:00 2001 From: Laurent Mazuel Date: Thu, 11 Nov 2021 15:17:50 -0800 Subject: [PATCH 6/7] Classifier Py3 Only --- doc/dev/packaging.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index ec4854fb2a4b..56338f882cc8 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -108,6 +108,7 @@ setup( classifiers=[ 'Development Status :: 4 - Beta', 'Programming Language :: Python', + 'Programming Language :: Python :: 3 :: Only', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', @@ -147,6 +148,7 @@ Since the package is Python 3 only, do NOT make this wheel universal. This usual - Remove `extra_requires` - Add `python_requires=">=3.7",` - Remove the Python 2 and 3.5/3.6 classifiers + - Add classifier `Programming Language :: Python :: 3 :: Only` - Remove the "azure" check if applicable (see next note) # Note on checking old Azure packages From 5044449274e14e70294f71ce9be619212bbe4e30 Mon Sep 17 00:00:00 2001 From: Laurent Mazuel Date: Tue, 16 Nov 2021 15:19:52 -0800 Subject: [PATCH 7/7] Update packaging.md --- doc/dev/packaging.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index 56338f882cc8..0a9dc3995c0a 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -1,6 +1,6 @@ # Azure packaging -This article describes the recommendation on how to define namespace packaging to release a package inside the `azure` namespace. Being inside the `azure` namespace meaning you have a service `myservice` that you want to import using: +This article describes the recommendations for defining namespace packaging to release a package inside the `azure` namespace. Being inside the `azure` namespace means that a service `myservice` can be imported using: ```python import azure.myservice ``` @@ -11,9 +11,9 @@ Namespace packaging is complicated in Python, here's a few reading if you still - https://github.com/pypa/sample-namespace-packages Note: -While this article provides example using setup.py, there is no problem with achieving it with setup.cfg or other methods, as long as the constraints on the final wheels/sdist are met. +While this article provides an example using setup.py, this can also be achieved with setup.cfg or other methods, as long as the constraints on the final wheels/sdist are met. -*This page has been updated to be Python 3 only packages as we do not recommend to support Python 2 after January 1st 2022.* If you still want to support Python 2 for some reasons, there is a section at the bottom with some details (or you have the Github history, to read the page as it was on November 1st 2021). +*This page has been updated to be Python 3 only packages as we do not recommend supporting Python 2 after January 1st 2022.* If you still want to support Python 2 for some reasons, there is a section at the bottom with some details (or you have the Github history, to read the page as it was on November 1st 2021). # What are the constraints? @@ -138,12 +138,12 @@ Since the package is Python 3 only, do NOT make this wheel universal. This usual # How can I check if my packages are built correctly? - wheel file must NOT contain a `azure/__init__.py` file (you can open it with a zip util to check) -- wheel file name finishes with `py3-none-any`, and NOT by `py2.py3-none-any`. +- wheel file name suffix is `py3-none-any`, and NOT `py2.py3-none-any`. - sdist must contain a `azure/__init__.py` file that declares `azure` as a namespace package using the `pkgutil` syntax # I already have a package that supports Python 2, can I get short version on how to udpate to Python 3 only? -- Remove "universal" from setup.cfg, or remove completly the file if it was the only option +- Remove "universal" from setup.cfg, or completly remove the file if it was the only option - In setup.py: - Remove `extra_requires` - Add `python_requires=">=3.7",` @@ -153,7 +153,7 @@ Since the package is Python 3 only, do NOT make this wheel universal. This usual # Note on checking old Azure packages -You may see code looking like this: +You may see code in `setup.py` looking like this: ```python # azure v0.x is not compatible with this package # azure v0.x used to have a __version__ attribute (newer versions don't)