Getting Ready for “Cheese Shop”

Introduction

Prolog

Because of deterioration of my memory, I need to make notes on a variety of tasks that I am involved in. Rather than writing on pieces of paper that even I myself can hardly read even if I do find the right piece of paper, I may as well write into my web pages. This may also be helpful for other people that plan similar activities as my own.

About

So what is this all about? The discussion about sphinx is part of the documentation for submission of programs to pypi. There are other tasks also.

This are very brief notes of useful staff for getting the programs or modules ready to be registered with and uploaded to the pypi:

Python Package Index aka "Cheese Shop"

The tasks are:

  • Select setup of directories and files
  • Write setup.py
  • register and upload

Setup

The Directories at Home

As an example, consider the submimission of a version of vectors32 to pypi. We do need following subdirectories at home:

vectors32-mod  -- for the files in module package.
vectors32-pdf  -- for the pdf manuals for end users.
vectors32-doc  -- for ReST files and html etc...
vectors32-tst  -- test files for testing module

vectors32-mod will be installed as vectors32 on the pypi and will become part of the tar ball for the end user. vectors32-doc are data files in ReStructured Text for our use only and will not be part of the tar ball. They will not upload to pypi, either, unless we give special instructions.

Files in vectors32 directory

On my PC this is the following directory:

/dat/work/py3/vectors32

where /dat is my data partition, immutable between installations of distros. We will continue to refer to it as:

vectors32

In that directory will be a README.txt file with basic instruction of installation and other basic information. It is automagically included in the tar ball by the setup. To include vectors32-pdf and vectors32-tst in the tar ball we need to create a MANIFEST.in text file in the vectors32 directory with two lines of code:

graft vectors32-pdf
graft vectors32-tst

That will auto generate the MANIFEST file in the vectors32 directory with the list of files that are included in the tar ball.

setup.py

I had some trouble to register my first attempt at the registration of a package at the Cheese Shop as I failed to give acceptable classifiers - the list of acceptable classifiers is easily obtained by the following command:

python setup.py register --list-classifiers

This yields a long list! It is important - better save it somewhere. At this juncture I better list a real setup.py file for vectors32:

from distutils.core import setup
.
setup(name='vectors32',
    version='0.0.5',
    description='Pure Python3 Vector Algebra Module.',
    long_description='''
===================
omitted for brevity
===================
.
information that will be shown by pypi presentation page
''',
    author='Algis Kabaila',
    author_email='algis.Kabaila@gmail.com',
    url='http://akabaila.pcug.org.au/StructuralAnalysis.pdf',
    packages=['vectors32'],
    package_dir={'vectors32' : 'vectors32-mod'},
    platforms='POSIX',
    license='LGPL',
    classifiers=[
        'Development Status :: 4 - Beta',
        'Environment :: Console',
        'Intended Audience :: End Users/Desktop',
        'Intended Audience :: Developers',
        'License :: OSI Approved :: GNU Library or Lesser General           Public License (LGPL)',
        'Operating System :: POSIX',
        'Programming Language :: Python',
        'Programming Language :: Python :: 3.2',
        'Topic :: Education',
      ],
 )

It is mostly self explanatory, except that the package_dir looks a little odd. In the tar ball and in the installation the package will be vectors32 whilst in my vectors32 directory it remains vectors32-mod. This is my choice to avoid confusion by too many directories bearing vectors32 name without qualifiers. The occasional “.” on empty lines is my device to deal with the vagaries of ReStructured Text interpretation of rst commands.

Registration and Upload to PyPI

With all the files in their appropriate directories, we can now proceed to the final two steps.

Registration

Before we can upload we need to become members of pypi - easy. Now we need to register the package to upload. I call it the same as name, which is vector32. It is convenient to inform pypi of your pypi user name and the pypi password, withou the need to reply in a dialog. One way to do that is to add a hidden file, named .pypirc, in the $HOME directory:

[server-login]
username:OldAl
password:xxx

Of course, xxx is your pypi password. As it is stored on your PC in plain text, it is advisable to obliterate the password when not in use. OldAl is my username and [server-login] is the magic header of the pypirc file.

The registration command, invoked from the vector32 directory, predictably is:

python setup.py register

When the registration is successful we can progress to the next step.

Uploading to pypi

We will probably want to have a final check to see that all has worked as planned, so we would issue the command:

python setup.py sdist

Read sdist as Source DISTribution - makes it easier to remember. This command creates the tar ball that can be locally extracted, inspected and tested. After that we are ready to upload:

python setup.py sdist upload

All done. Reward yourself with your favourite drink!