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

@theacodes theacodes 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

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
Copy link
Sponsor Member

@di di 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.
Copy link
Sponsor Member

@di di May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@ncoghlan ncoghlan May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Sponsor Member

@di di May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Sponsor Member

@di di May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, done.


python3 -m pip install --user --upgrade twine

Once install, run twine to upload all of the archives under :file:`dist`:
Copy link
Sponsor Member

@di di May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Once installed"

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. Fixed.


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

Copy link
Sponsor Member

@di di May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call, done.

# Example Package

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

@pfmoore pfmoore May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. Fixed.

@theacodes
Copy link
Member Author

theacodes commented May 17, 2018

di
di approved these changes May 17, 2018
Copy link
Sponsor Member

@di di left a comment

Two small nits, otherwise LGTM!

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

This tutorial uses a simple project named `example_pkg`. If you are unfamiliar
Copy link
Sponsor Member

@di di May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be example_pkg and not example_pkg?

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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):
Copy link
Sponsor Member

@di di May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@theacodes theacodes May 17, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

@theacodes
Copy link
Member Author

theacodes commented May 17, 2018

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

Copy link
Member

@pradyunsg pradyunsg 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
Copy link
Member

@pradyunsg pradyunsg May 18, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@theacodes
Copy link
Member Author

theacodes commented May 18, 2018

@ncoghlan very gentle ping

@ncoghlan
Copy link
Member

ncoghlan 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!

Copy link
Member

@ncoghlan ncoghlan 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.
Copy link
Member

@ncoghlan ncoghlan May 20, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@theacodes theacodes May 20, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@theacodes theacodes merged commit 927eca1 into pypa:master May 20, 2018
1 check passed
@theacodes
Copy link
Member Author

theacodes commented May 20, 2018

Thanks everyone!

@theacodes theacodes deleted the new-distributing-tutorial branch May 20, 2018
@di di mentioned this pull request Nov 15, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants