Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create new, simpler packaging tutorial #498

Merged
merged 5 commits into from May 20, 2018

Conversation

@theacodes
Copy link
Member

commented May 17, 2018

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

Create new, simpler packaging tutorial
Move the existing tutorial into guides/distributing-packages-using-setuptools to be cleaned up later.

@theacodes theacodes requested a review from ncoghlan May 17, 2018

@di
Copy link
Member

left a comment

Looks really great to me overall! Just some small suggestions from my perspective.


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.

This comment has been minimized.

Copy link
@di

di May 17, 2018

Member

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.

This comment has been minimized.

Copy link
@ncoghlan

ncoghlan May 17, 2018

Member

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.

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

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.

This comment has been minimized.

Copy link
@di

di May 17, 2018

Member

This almost seems like we prefer the MIT license. It might be good to say something like:

Once you have chosen a license, open LICENSE and enter the license text. For example, if you had chosen the MIT license:

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

Good call, done.


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

This comment has been minimized.

Copy link
@di

di May 17, 2018

Member

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.

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

Agreed, done.

python3 -m pip install --user --upgrade twine
Once install, run twine to upload all of the archives under :file:`dist`:

This comment has been minimized.

Copy link
@di

di May 17, 2018

Member

"Once installed"

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

Good catch. Fixed.


**Congratulations, you've packaged and distributed a Python library!**
✨ 🍰 ✨

This comment has been minimized.

Copy link
@di

di May 17, 2018

Member

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.

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

Good call, done.

# Example Package

This is a simple example package. You can use
[Github-flavored Markdown](http://TODO) to write your content.

This comment has been minimized.

Copy link
@pfmoore

pfmoore May 17, 2018

Member

Still got a TODO here. This is the link to the Markdown help github provides: https://guides.github.com/features/mastering-markdown/

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

Good catch. Fixed.

@theacodes

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

@di

di approved these changes May 17, 2018

Copy link
Member

left a comment

Two small nits, otherwise LGTM!

A simple project
----------------

This tutorial uses a simple project named `example_pkg`. If you are unfamiliar

This comment has been minimized.

Copy link
@di

di May 17, 2018

Member

Should this be example_pkg and not example_pkg?

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

Done.

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):

This comment has been minimized.

Copy link
@di

di May 17, 2018

Member

Maybe "Run the Python interpreter?" Either way I think "Python" should be capitalized.

This comment has been minimized.

Copy link
@theacodes

theacodes May 17, 2018

Author Member

Done.

@theacodes

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

Thanks for the review, @di! I will wait for @ncoghlan to approve as well

@pradyunsg
Copy link
Member

left a comment

🎉

.. 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

This comment has been minimized.

Copy link
@pradyunsg

pradyunsg May 18, 2018

Member

minor nit -- one place used dash, suggested workaround uses underscore; both should be the same.

@theacodes

This comment has been minimized.

Copy link
Member Author

commented May 18, 2018

@ncoghlan very gentle ping

@ncoghlan

This comment has been minimized.

Copy link
Member

commented May 20, 2018

Heh, I was avoiding my GitHub folder since dozens of messages had built up during PyCon and my trip home :)

Reviewing now!

@ncoghlan
Copy link
Member

left a comment

This looks good to me, just one question/suggestion about the Test PyPI reminder.

✨ 🍰 ✨

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.

This comment has been minimized.

Copy link
@ncoghlan

ncoghlan May 20, 2018

Member

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?"

This comment has been minimized.

Copy link
@theacodes

theacodes May 20, 2018

Author Member

Great point. Done - just made it the leading sentence in this paragraph.

theacodes added some commits May 20, 2018

@theacodes theacodes merged commit 927eca1 into pypa:master May 20, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@theacodes

This comment has been minimized.

Copy link
Member Author

commented May 20, 2018

Thanks everyone!

@theacodes theacodes deleted the theacodes:new-distributing-tutorial branch May 20, 2018

@di di referenced this pull request Nov 15, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.