annotate README.txt @ 77:4415ba355f25

flush out README
author Jeff Hammel <jhammel@mozilla.com>
date Fri, 02 Mar 2012 16:03:37 -0800
parents 5fbe4374bc8a
children d5c3fdceb718
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
93e830409685 initial stub commit
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
1 simpypi
33
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
2 =======
0
93e830409685 initial stub commit
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
3
75
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
4 Simple python package index
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
5
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
6 How simpypi works
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
7 -----------------
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
8
76
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
9 The heart of simpypi is ``simpypi.wsgi.SimPyPI``, a simple
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
10 `WSGI <http://www.python.org/dev/peps/pep-0333/>`_ web app that
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
11 accepts a uploaded
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
12 `python package <http://guide.python-distribute.org/introduction.html>`_
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
13 distribution and places it according to its name and version metadata
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
14 appropriate to the
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
15 `simple index protocol <http://guide.python-distribute.org/contributing.html#the-simple-index-protocol>`_ .
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
16
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
17 For security, ``SimPyPI`` returns straight
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
18 `HTTP 400 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ s
77
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
19 for invalid requests. This could probably be improved.
76
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
20
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
21 ``SimPyPI`` itself does not serve this directory. The directory
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
22 should be served by a fileserver that will generate directory indices
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
23 (as apprpropriate to
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
24 http://guide.python-distribute.org/contributing.html#the-simple-index-protocol
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
25 ) such as Apache or
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
26 `FileServer <http://pypi.python.org/pypi/FileServer>`_ .
77
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
27 ``simpypi.factory.factory`` does provide a factory to make a WSGI app
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
28 that wraps ``FileServer`` in middleware and serves the simple index
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
29 under ``/index/`` and the ``SimPyPI`` app at ``/``. Additionally, a
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
30 ``simpypi`` command line program is provided that front-ends this.
76
5fbe4374bc8a more documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 75
diff changeset
31
75
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
32 Currently ``simpypi`` only works on source distributions (that is,
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
33 packages made with ``python setup.py sdist``).
0
93e830409685 initial stub commit
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
34
33
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
35 Running the Tests
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
36 -----------------
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
37
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
38 ``tests-require.txt`` contains dependencies that should be installed
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
39 to run the tests.
77
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
40 `Paste <http://pythonpaste.org/>`_
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
41 `TestApp <http://pythonpaste.org/testing-applications.html>`_ ,
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
42 though this could be transitioned to
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
43 `WebTest <http://webtest.pythonpaste.org/en/latest/index.html>`_ .
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
44 `virtualenv <http://www.virtualenv.org/>`_
4415ba355f25 flush out README
Jeff Hammel <jhammel@mozilla.com>
parents: 76
diff changeset
45 is used for isolating python environments.
33
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
46
39
619b7612c7e9 note in todo
Jeff Hammel <jhammel@mozilla.com>
parents: 33
diff changeset
47 TODO
619b7612c7e9 note in todo
Jeff Hammel <jhammel@mozilla.com>
parents: 33
diff changeset
48 ----
619b7612c7e9 note in todo
Jeff Hammel <jhammel@mozilla.com>
parents: 33
diff changeset
49
75
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
50 While simpypi is pretty simple, just because it is only 100 lines of
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
51 code doesn't mean that it is the *right* 100 lines of code. The
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
52 following issues could be addressed:
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
53
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
54 * the temporary package should be dealt with entirely in memory,
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
55 ideally. Currently we write to a file and move it.
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
56
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
57 * ``simpypi`` use ``pkginfo.sdist`` to read the data from a source
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
58 distribution. Instead, the uploaded package should probably be
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
59 unpacked and ``python setup.py sdist`` run and the resulting
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
60 package put in the appropriate place. This will allow archives
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
61 without ``PKG-INFO``
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
62 (e.g. http://hg.mozilla.org/build/talos/archive/tip.tar.gz )
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
63 to be uploaded as well as at least partially correct for the fact
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
64 that currently ``simpypi`` only works for uploaded source
809153401986 update documentation
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
65 distributions.
39
619b7612c7e9 note in todo
Jeff Hammel <jhammel@mozilla.com>
parents: 33
diff changeset
66
0
93e830409685 initial stub commit
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
67 --
93e830409685 initial stub commit
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
68
33
058182b7b309 note test-requires.txt in the readme
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
69 http://k0s.org/mozilla/hg/simpypi