Create new, simpler packaging tutorial #498
Conversation
Move the existing tutorial into guides/distributing-packages-using-setuptools to be cleaned up later.
|
|
||
| This tutorial walks you through how to package a simple Python library. It will | ||
| show you how to add the necessary files and structure to create the package, how | ||
| to build the package, and how to upload it to the Python Package Index. |
There was a problem hiding this comment.
Would it make sense to link to various terms in the glossary as they are introduced in this guide? In addition, "library" is not even in the glossary, so it might be confusing if this is the first page of the guide a user sees.
There was a problem hiding this comment.
We mainly stuck with the phrase "project" to avoid having to make the distinction, and saying "Python projects use pyproject.toml" (once this guide is able to switch to that) would make sense.
There was a problem hiding this comment.
Good call, I went ahead and replaced "library" with "project".
@di I tried to be really liberal with links to the glossary, but let me know if I missed any.
| a license. This tells users who install your package the terms under which they | ||
| can use your package. For help picking a license, see | ||
| https://choosealicense.com/. For now, open :file:`LICENSE` and enter the | ||
| following content - which is the MIT license. |
There was a problem hiding this comment.
This almost seems like we prefer the MIT license. It might be good to say something like:
Once you have chosen a license, open
LICENSEand enter the license text. For example, if you had chosen the MIT license:
|
|
||
| The ``tar.gz`` file is a :term:`source archive` - it is intended mostly for | ||
| downstream packagers (such as Linux distros) or users who have disabled | ||
| installing built distributions. The ``.whl`` file is a :term:`built |
There was a problem hiding this comment.
I think we should be a little stronger about why users should upload source distributions.
The "it is intended mostly for downstream packagers" bit will probably read to a new user (who is unfamiliar with who or what downstream packagers are) that it's unnecessary.
One current headache on PyPI is that sometimes maintainers only upload wheels for a release, and users who have incompatible platform have no way to install that given release. In addition, source distributions are also a little easier to audit.
Something as strong as "You should always upload a source distribution for a release" would be ideal, IMO.
|
|
||
| python3 -m pip install --user --upgrade twine | ||
|
|
||
| Once install, run twine to upload all of the archives under :file:`dist`: |
|
|
||
| **Congratulations, you've packaged and distributed a Python library!** | ||
| ✨ 🍰 ✨ | ||
|
|
There was a problem hiding this comment.
This might be a good place to remind readers that TestPyPI is ephemeral, and that this package will go away someday, so if they truly want to make it available to users they will need to upload it to PyPI.
| # Example Package | ||
|
|
||
| This is a simple example package. You can use | ||
| [Github-flavored Markdown](http://TODO) to write your content. |
There was a problem hiding this comment.
Still got a TODO here. This is the link to the Markdown help github provides: https://guides.github.com/features/mastering-markdown/
|
Restaged over at: http://temp.theadora.io/pypug/tutorials/packaging-projects.html |
| A simple project | ||
| ---------------- | ||
|
|
||
| This tutorial uses a simple project named `example_pkg`. If you are unfamiliar |
There was a problem hiding this comment.
Should this be example_pkg and not example_pkg?
| You can test that it was installed correctly by importing the module and | ||
| referencing the ``name`` property you put in :file:`__init__.py` earlier. | ||
|
|
||
| Run python (make sure you're still in your virtualenv): |
There was a problem hiding this comment.
Maybe "Run the Python interpreter?" Either way I think "Python" should be capitalized.
| .. note:: If you get an error that says ``The user '[your username]' isn't | ||
| allowed to upload to project 'example-pkg'``, you'll need to go and pick | ||
| a unique name for your package. A good choice is | ||
| ``example_pkg_your_username``. Update the ``name`` argument in |
There was a problem hiding this comment.
minor nit -- one place used dash, suggested workaround uses underscore; both should be the same.
|
@ncoghlan very gentle ping |
|
Heh, I was avoiding my GitHub folder since dozens of messages had built up during PyCon and my trip home :) Reviewing now! |
| ✨ 🍰 ✨ | ||
|
|
||
| If you want to upload your package to the real Python Package Index you can do | ||
| it by registering an account on https://pypi.org and following the same | ||
| instructions above but omitting the ``--repository-url`` argument to ``twine`` | ||
| and the ``--index-url`` argument to ``pip``. | ||
| and the ``--index-url`` argument to ``pip``. Note that Test PyPI is emphermal | ||
| and it's not unusual for packages and accounts to be deleted occasionally. |
There was a problem hiding this comment.
Typo for "ephemeral", but I'm also wondering if this might read better as a separate paragraph preceding this one. That way the paragraph about the real PyPI reads like an answer to the follow-on question of "OK, you've reminded me that this is ephemeral, so how do I make it persistent?"
There was a problem hiding this comment.
Great point. Done - just made it the leading sentence in this paragraph.
|
Thanks everyone! |
Move the existing tutorial into guides/distributing-packages-using-setuptools to be cleaned up later.
Staged: http://temp.theadora.io/pypug/tutorials/packaging-projects.html
Resolves #494
Resolves #298
Resolves #203