diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 000000000..a72b4d9ce --- /dev/null +++ b/.travis.yml @@ -0,0 +1,5 @@ +language: python +python: + - "2.7" +install: "pip install Sphinx" +script: "make SPHINXOPTS='-W' html" diff --git a/source/contribute.rst b/source/contribute.rst new file mode 100644 index 000000000..198d3736d --- /dev/null +++ b/source/contribute.rst @@ -0,0 +1,156 @@ +.. |PyPUG| replace:: Python Packaging User Guide + +************************ +Contribute to this guide +************************ + +The |PyPUG| welcomes contributors! There are lots of ways to help out, +including: + +* Reading the guide and giving feedback +* Reviewing new contributions +* Revising existing content +* Writing new content + +Most of the work on the |PyPUG| takes place on the +`project's GitHub repository`__. To get started, check out the list of +`open issues`__ and `pull requests`__. If you're planning to write or edit +the guide, please read the :ref:`style guide `. + +.. __: https://github.com/pypa/python-packaging-user-guide/ +.. __: https://github.com/pypa/python-packaging-user-guide/issues +.. __: https://github.com/pypa/python-packaging-user-guide/pulls + +By contributing to the |PyPUG|, you're expected to follow the Python +Packaging Authority's `Contributor Code of Conduct`__. Harassment, personal +attacks, and other unprofessional conduct is not acceptable. + +.. __: https://www.pypa.io/en/latest/code-of-conduct/ + + +.. _contributing_style_guide: + +Style guide +=========== + +This style guide has recommendations for how you should write the |PyPUG|. +Before you start writing, please review it. By following the style guide, your +contributions will help add to a cohesive whole and make it easier for your +contributions to be accepted into the project. + + +Purpose +------- + +The purpose of the |PyPUG| is + + to be the authoritative resource on how to package, publish and install + Python distributions using current tools + + +Scope +----- + +The guide is meant to answer questions and solve problems with accurate and +focused recommendations. + +The guide isn't meant to be comprehensive and it's not meant to replace +individual projects' documentation. For example, pip has dozens of commands, +options, and settings. The pip documentation describes each of them in +detail, while this guide describes only the parts of pip that are needed to +complete the specific tasks described in this guide. + + +Audience +-------- + +The audience of this guide is anyone who uses Python with packages. + +Don't forget that the Python community is big and welcoming. Readers may not +share your age, gender, educational background, cultural background, and +more, but they're just as deserving to learn about packaging as you are. + +In particular, keep in mind that not all people who use Python see themselves +as programmers. They might be astronomers or painters or students, not just +professional software developers. + + +Voice and tone +-------------- + +When writing this guide, strive to write with a voice that's approachable +and humble, even if you have all the answers. + +Imagine you're working on a Python project with someone you know to be smart +and skilled. You like working with them and they like working with you. That +person has asked you a question. How do you respond? *That* is how you +should write this guide. + +Here's a quick check: try reading aloud to get a sense for your writing's +voice and tone. Does it sound like something you would say or does it sound +like you're acting out a part of giving a speech? Feel free to use +contractions and don't worry about sticking to fussy grammar rules. You are +hereby granted permission to end a sentence in a preposition. + +When writing the guide, adjust your tone for the seriousness and difficulty +of the topic. If you're writing an introductory tutorial, it's OK to make a +joke, but if you're covering a sensitive security recommendation, you might +want to avoid jokes altogether. + + +Conventions and mechanics +------------------------- + +**Write to the reader** + When giving recommendations or steps to take, address the reader as *you* + or use the imperative mood. + + | Wrong: To install it, the user runs… + | Right: You can install it by running… + | Right: To install it, run… + +**State assumptions** + Avoid making unstated assumptions. Reading on the web means that any page of + the guide may be the first page of the guide that the reader ever sees. + If you're going to make assumptions, then say what assumptions that you're + going to make. + +**Cross-reference generously** + The first time you mention a tool or practice, link to the part of the + guide that covers it, or link to a relevant document elsewhere. Save the + reader a search. + +**Respect naming practices** + When naming tools, sites, people, and other proper nouns, use their preferred + capitalization. + + | Wrong: Pip uses… + | Right: pip uses… + | + | Wrong: …hosted on github. + | Right: …hosted on GitHub. + +**Use a gender-neutral style** + Often, you'll address the reader directly with *you*, *your* and *yours*. + Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or + avoid pronouns entirely. + + | Wrong: A maintainer uploads the file. Then he… + | Right: A maintainer uploads the file. Then they… + | Right: A maintainer uploads the file. Then the maintainer… + +**Headings** + Write headings that use words the reader is searching for. A good way to + do this is to have your heading complete an implied question. For example, a + reader might want to know *How do I install MyLibrary?* so a good heading + might be *Install MyLibrary*. + + In section headings, use sentence case. In other words, write headings as you + would write a typical sentence. + + | Wrong: Things You Should Know About Python + | Right: Things you should know about Python + +**Numbers** + In body text, write numbers one through nine as words. For other numbers or + numbers in tables, use numerals. diff --git a/source/index.rst b/source/index.rst index 0ee3be28b..13a4405c4 100644 --- a/source/index.rst +++ b/source/index.rst @@ -16,6 +16,7 @@ This guide is maintained on `github .. toctree:: :maxdepth: 1 + packaging_tutorials current installing distributing @@ -24,6 +25,7 @@ This guide is maintained on `github key_projects glossary support + contribute .. _docs.python.org: http://docs.python.org diff --git a/source/packaging_tutorials.rst b/source/packaging_tutorials.rst new file mode 100644 index 000000000..8d988a5b7 --- /dev/null +++ b/source/packaging_tutorials.rst @@ -0,0 +1,18 @@ +========================= +Introduction to Packaging +========================= + +:Last Reviewed: Pending + +.. note:: + + This tutorial is a work in progress. Please see `issue #194`__ for details. + + .. __: https://github.com/pypa/python-packaging-user-guide/issues/194 + + +.. toctree:: + :maxdepth: 1 + + prerequisites + using-a-virtualenv diff --git a/source/prerequisites.rst b/source/prerequisites.rst new file mode 100644 index 000000000..4e1e03be0 --- /dev/null +++ b/source/prerequisites.rst @@ -0,0 +1,106 @@ +Prerequisites for Creating Packages +=================================== + +In order to complete the following tutorial, you must have pip, setuptools +and wheel installed. The section below describes the steps for installation. +Please note the latest versions of Python include pip. + + +Install pip, setuptools and wheel +--------------------------------- + +To install pip, setuptools and wheel, you must have a version of Python +installed. You can verify if there is a version of Python in your +system by entering the following into your terminal or command prompt. + +.. code-block:: shell + + python --version + +If a version number is returned (for example: python 3.5.0), then +Python is installed. + +Once you have verified a version of Python is installed in your system, +you may proceed verifying/installing/upgrading pip, setuptools and +wheel in your system. + + +pip +---- + +To verify if pip is installed in your system, enter +the following into your command prompt. + +.. code-block:: shell + + pip --version + +If a version number is returned (for example: pip 7.X.X), then +pip is installed. + +If pip is not installed, download get-pip.py from here_. + +.. _here: https://bootstrap.pypa.io/get-pip.py + +After downloading, run the following command in +your prompt as this will install pip. + +.. code-block:: shell + + python get-pip.py + +If pip is installed and needs to be upgraded, enter the following command. + +.. code-block:: shell + + pip install --upgrade pip + + +setuptools +----------- + +Once you have verified/upgraded pip in your system, you'll need to +verify if you have setuptools installed. To verify, enter the following into +your command prompt and you'll see a list of packages managed by pip. + +.. code-block:: shell + + pip list + +Scroll through the list, which is listed alphabetically, and locate setuptools. + +If setuptools is not installed, enter the following into your command prompt. + +.. code-block:: shell + + pip install setuptools + +If setuptools needs to be upgraded, enter the following command. + +.. code-block:: shell + + pip install --upgrade setuptools + + +wheel +----- + +Similar to setuptools verification, to verify if wheel +is installed, enter the following and locate wheel. + +.. code-block:: shell + + pip list + +If wheel is not installed already, enter the following +into your command prompt. + +.. code-block:: shell + + pip install wheel + +To upgrade, enter the following into your command prompt. + +.. code-block:: shell + + pip install --upgrade wheel diff --git a/source/using-a-virtualenv.rst b/source/using-a-virtualenv.rst new file mode 100644 index 000000000..58f15e3e9 --- /dev/null +++ b/source/using-a-virtualenv.rst @@ -0,0 +1,180 @@ +========================== +Using virtual environments +========================== + +By default, when you use ``pip`` to install packages, it will install +them in a default location where all other packages are installed. This +default behaviour may however not be desirable. The solution is to to create +isolated *virtual environments* in which you can install packages. You can +think of isolated environments as individual sandboxes. By having a separate +virtual environment for each of your projects, you will keep the packages +installed in each project separate from one another. + +Installation +------------ + +If you are using Python 2 or Python 3 (up to and including Python 3.2), +install `virtualenv `__ using +``pip install virtualenv`` or ``pip3 install virtualenv``, respectively. You +will then be able to create and work with virtual environments via the +``virtualenv`` command. + +If you are using Python 3.3 or a more recent version, support for +creating virtual environments should already be installed and accessible via the +``python -m venv`` command (on some systems, the equivalent ``pyvenv`` command +may also be available). + +For the rest of the guide, ``python -m venv`` will be used as the command for +creating virtual environments, with the assumption that you are using Python 3.3 +or greater. However, for older Python versions, ``virtualenv`` should work the +same. + +Creating a virtual environment +------------------------------ + +The first step is to create a virtual environment which creates a new +subdirectory at your specified location. It may be a good idea to +have all your virtual environments under one sub-directory. Let's +assume that you want the new virtual environment ``tabulate`` to be +created in the subdirectory ``$HOME/work/virtualenvs`` where +``$HOME`` refers to the user's home directory on Linux and Mac +OS X. The following command will carry out this operation: + +.. code:: + + $ python -m venv ~/work/virtualenvs/tabulate + +If you are on Windows, assuming that you want the new virtualenv to be +created under ``C:\work\virtualenvs``, the equivalent command would be: + +.. code:: + + > python -m venv C:\work\virtualenvs\tabulate + +A new virtual environment ``tabulate`` has now been created for us. To +be able to install packages in it, you need to *activate* it. + +Activating a virtual environment and installing packages +-------------------------------------------------------- + +On Linux/Mac OS X you can activate our virtual environment, +``tabulate`` via the following command: + +.. code:: + + $ source ~/work/virtualenvs/tabulate/bin/activate + +On Windows, the command to activate the virtual environment is: + +.. code:: + + > \work\virtualenvs\tabulate\Scripts\activate + +Now, you are in the virtual environment. To see the packages currently +installed in the virtual enviroment, you can use the ``pip list`` command: + +.. code:: + + (tabulate) $ pip3 list + pip (7.1.0) + setuptools (18.0.1) + +You can see that only two packages installed in the virtual environment. You +can install our desired packages using ``pip`` now. As an example of a package, +you will install and use the `tabulate +`__ package. It is an easy way +to display tabular data without having to do a lot of tedious work yourself. + +.. code :: + + (tabulate) $ pip install tabulate + Collecting tabulate + Using cached tabulate-0.7.5.tar.gz + Installing collected packages: tabulate + Running setup.py install for tabulate + Successfully installed tabulate-0.7.5 + +Our package is now installed, so try running a simple example to see how it +works. + +Using the package +----------------- + +The program below will print a table consisting of the numbers in a +list and how many times each appears as a table: + +.. code:: + + from collections import Counter + from tabulate import tabulate + + def frequency_table(numbers): + table = Counter(numbers) + rows = [] + for number in table.most_common(): + rows.append([number[0], number[1]]) + print(tabulate(rows, headers=['Number', 'Frequency'])) + + if __name__=='__main__': + scores = [7, 8, 9, 2, 10, 9, 9, 9, 9, 4, 5, 6, 1, 5, 6, 7, 8, 6, 1, 10] + frequency_table(scores) + + +Save the above program to a file and run it while within the virtual +environment. Run the ``python`` or ``python3`` command and passing the file name +you saved the program to as the first argument: + +.. code:: + + $ python + +You should see the following output when run: + +.. code:: + + Number Frequency + -------- ----------- + 9 5 + 6 3 + 1 2 + 5 2 + 7 2 + 8 2 + 10 2 + 2 1 + 4 1 + + +Feel free to explore the ``tabulate`` package more to see the +different types of tables you can create with it. + +Deactivating a virtual environment +---------------------------------- + +Once you are done working in the virtual environment, the +``deactivate`` command will deactivate the virtual environment: + +.. code:: + + (tabulate) $ deactivate + +Deleting a virtual environment +------------------------------ + +Over time, the number of virtual environments can increase and you may +want to remove the ones you don't need anymore. To do so, delete the directory +for the virtual enviroment. For example, for the ``tabulate`` virtual +environment created above, delete the ``tabulate`` directory from +``$HOME/work/virtualenvs`` on Linux/Mac OS X or ``C:\work\virtualenvs`` +on Windows. + +Key steps +--------- + +To summarize, here are the steps when working with virtual environments: + +- Create a virtual environment using ``python -m venv``, ``pyvenv``, or + ``virtualenv`` +- Activate it using the ``activate`` script +- Work +- Deactivate using ``deactivate``