Publishing Python Packages: Test, share, and automate your projects

250 Pages·2023·14.806 MB·English

by  Dane Hillard

Test, share, and automate your projects
Dane Hillard
Foreword by David Beazley
M A N N I N G
Project GitHubActions
GitHubActions
Packagefiles Format
configuration
Lint 3. You can configure
1. Your project contains different sequential
Check out code
both the code for your and parallel steps to
package as well as the Set up Python run in the continuous
Type check
configuration for integration process,
Install dependencies
automatically building which can each provide
and testing it in a Run task pass/fail feedback back
continuous integration Test to the pull request.
environment such as
GitHub Actions.
Check
statuses Build
wheels
File changes Pull request
Build
2. When you make changes
source
to your package code and Merge
distribution
open a pull request, the
continuous integration
workflow is triggered. Tag Publish
4. After all your continuous
integration checks are
5. After you merge enough changes to constitute
passing, you can merge the
a release, you can tag the latest commit with a
pull request with confidence.
version, triggering the continuous integration
process to build all package artifacts and publish
them to a package repository such as PyPI.
Publishing Python Packages

Publishing
Python Packages
TEST, SHARE, AND AUTOMATE YOUR PROJECTS
DANE HILLARD
Foreword by DAVID BEAZLEY
MANNING
SHELTER ISLAND
For online information and ordering of this and other Manning books, please visit
www.manning.com. The publisher offers discounts on this book when ordered in quantity.
For more information, please contact
Special Sales Department
Manning Publications Co.
20 Baldwin Road
PO Box 761
Shelter Island, NY 11964
Email: [email protected]
©2023 by Manning Publications Co. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in
any form or by means electronic, mechanical, photocopying, or otherwise, without prior written
permission of the publisher.
Many of the designations used by manufacturers and sellers to distinguish their products are
claimed as trademarks. Where those designations appear in the book, and Manning Publications
was aware of a trademark claim, the designations have been printed in initial caps or all caps.
Recognizing the importance of preserving what has been written, it is Manning’s policy to have
the books we publish printed on acid-free paper, and we exert our best efforts to that end.
Recognizing also our responsibility to conserve the resources of our planet, Manning books
are printed on paper that is at least 15 percent recycled and processed without the use of
elemental chlorine.
The author and publisher have made every effort to ensure that the information in this book
was correct at press time. The author and publisher do not assume and hereby disclaim any
liability to any party for any loss, damage, or disruption caused by errors or omissions, whether
such errors or omissions result from negligence, accident, or any other cause, or from any usage
of the information herein.
Manning Publications Co. Development editor: Toni Arritola
20 Baldwin Road Technical development editor: Al Krinker
PO Box 761 Review editor: Aleksandar Dragosavljevic´
Shelter Island, NY 11964 Production editor: Andy Marinkovich
Copy editor: Pamela Hunt
Proofreader: Melody Dolab
Technical proofreader: Alex Agarkov
Typesetter: Dennis Dalinnik
Cover designer: Marija Tudor
ISBN: 9781617299919
Printed in the United States of America
brief contents
PART 1 FOUNDATIONS ..............................................................1
1 ■ The what and why of Python packages 3
2 ■ Preparing for package development 15
3 ■ The anatomy of a minimal Python package 21
PART 2 CREATING A VIABLE PACKAGE.......................................39
4 ■ Handling package dependencies, entry points,
and extensions 41
5 ■ Building and maintaining a test suite 56
6 ■ Automating code quality tooling 82
PART 3 GOING PUBLIC..........................................................101
7 ■ Automating work through continuous integration 103
8 ■ Authoring and maintaining documentation 128
9 ■ Making a package evergreen 158
v
vi BRIEF CONTENTS
PART 4 THE LONG HAUL .......................................................177
10 ■ Scaling and solidifying your practices 179
11 ■ Building a community 195
contents
foreword xi
preface xiii
acknowledgments xv
about this book xvii
about the author xxi
about the cover illustration xxii
PART 1 FOUNDATIONS ....................................................1
1 The what and why of Python packages 3
1.1 What is a package, anyway? 4
Standardizing packaging for automation 5 ■ The contents of a
distribution package 6 ■ The challenges of sharing software 7
1.2 How packaging helps you 7
Enforcing cohesion and encapsulation through packaging 8
Promoting clear ownership of code 9 ■ Decoupling implementation
from usage 10 ■ Filling roles by composing small packages 12
2 Preparing for package development 15
2.1 Managing Python virtual environments 16
Creating virtual environments with venv 18
vii
viii CONTENTS
3 The anatomy of a minimal Python package 21
3.1 The Python build workflow 22
Parts of the Python build system 22
3.2 Authoring package metadata 26
Required core metadata 26 ■ Optional core metadata 28
Specifying a license 31
3.3 Controlling source code and file discovery 33
3.4 Including non-Python files in a package 35
PART 2 CREATING A VIABLE PACKAGE.............................39
4 Handling package dependencies, entry points,
and extensions 41
4.1 A package for calculating vehicle drift 41
4.2 Creating a C extension for Python 44
Creating C extension source code 44 ■ Integrating Cython into
a Python package build 45 ■ Installing and profiling your C
extension 47 ■ Build targets for binary wheel distributions 48
Specifying required Python versions 50
4.3 Offering command-line tools from a Python package 50
Creating commands with Setuptools entry points 50
4.4 Specifying dependencies for Python packages 53
4.5 Answer to exercises 54
5 Building and maintaining a test suite 56
5.1 Integrating a testing setup 57
The pytest testing framework 57 ■ Adding test coverage
measurement 59 ■ Increasing test coverage 65
5.2 Addressing testing tedium 69
Addressing repetitive, data-driven tests 69 ■ Addressing frequent
package installation 70 ■ Configuring test environments 74
Tips for quicker and safer testing 76
5.3 Answers to exercises 80
6 Automating code quality tooling 82
6.1 The true power of tox environments 83
Creating nondefault tox environments 83 ■ Managing
dependencies across tox environments 85