1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
Packaging for XStatic
=====================
It's easy, no rocket-scientist needed.
We suggest you just take XStatic-jQuery package as a template and do these
steps:
* Copy XStatic-jQuery to XStatic-FooBar (replace "FooBar" by the official name
[display_name] of the project you are packaging).
* Rename xstatic/pkg/jquery package directory to xstatic/pkg/foobar (use
simple all-lowercase name, only a..z - this must be a valid python package
name [name]).
* Remove xstatic/pkg/foobar/data/* and place FooBar project's static files
there.
* Edit xstatic/pkg/foobar/__init__.py and update all information there
appropriately (see the comments there and also the hints below).
Most stuff from there will get reused by setup.py.
Do not forget to use some appropriate class name.
* Edit setup.py:
- You need to change the "from xstatic.pkg..." appropriately to import your
class.
- Review the rest of it, but most stuff should be fine as it just reuses
stuff from XStatic metadata.
* Edit MANIFEST.in and change the recursive-include statement there to refer
to your files (xstatic/pkg/foobar), so that your static files will be
included in the package created later.
* Edit README.txt and replace references to jQuery with FooBar.
This file's content will also be shown as long description on PyPi.
Please note that this file is written in reST markup, so that PyPi can
generate your project's page from it.
* If you use Mercurial, update .hgignore so it ignores:
^XStatic_FooBar.egg-info/
* Review all the stuff you did, make sure you did not forget anything, make
sure there is no jquery reference left.
* Run python setup.py sdist.
* Look into build/... - there should be your XStatic-FooBar package now.
* Test it locally:
- E.g. use pip install XStatic-FooBar-1.0.0.tar.gz to install it.
- Use it from your project, does it work?
* If you are happy with it and you think the package is also useful for many
other Pythonistas, register and upload it to PyPi:
python setup.py sdist register upload
Misc. Hints
===========
Names
-----
There are 3 names involved and you should follow these rules:
* XStatic subclass name: choose something starting with a uppercase letter
to follow PEP8 naming convention. E.g. FooBar or JQuery, not foobar nor
jQuery.
* name (metadata): simple, all lowercase name. E.g. foobar or jquery.
If you would have to use "-": please replace it by "_". Minus is not valid
in Python package names, so use underscore so that you can use same name
for your package directory / package name.
* display_name (metadata): the name as the upstream project itself spells it,
e.g. jQuery or FooBar. No spaces.
Note: if you are not packaging original files, but modified files, then you
must use a name that makes this fact obvious.
Version Numbers
---------------
As you are just repackaging another project, you should use the upstream
version number (or at least something closely related to it).
As you maybe do not get packaging right on the first try, we suggest appending
a build number, like:
* Upstream version: 1.2.3, XStatic-FooBar version: 1.2.3.0 (initial package)
* Upstream version: 1.2.3, XStatic-FooBar version: 1.2.3.1 (fixed package)
* Upstream version: 1.2.4, XStatic-FooBar version: 1.2.4.0 (initial package)
Some projects do not have such version numbers, make the best of it:
* Upstream version: 2010-12-31, XStatic-FooBar version: 2010.12.31.0
Which files to put into your package?
-------------------------------------
It is suggested that you only package files that are useful for Python
projects, because XStatic packages will be only used by them. No need for PHP,
ASP, Java, etc. related files.
If you package files that are somehow "compiled/compressed" versions, we
suggest you only package the files needed for production usage, not the source
code.
If the original download archive has the files needed for production in some
subdirectory, we suggest you strip the directory hierarchy and just put the
production files/directories into xstatic/pkg/foobar/data/.
CDN locations
-------------
If your files are available via a public CDN (Content Distribution Network),
you can give the URLs via the locations metadata.
If you do not have a CDN for the files, just use locations = {}.
Licensing
---------
You should put your XStatic-FooBar package under same license as the upstream
FooBar package. This avoids licensing complications and is also appropriate
because you only added a little metadata anyway.
Notes for Linux (or other OS) Package Maintainers
=================================================
If you are maintaining packages for some other packaging system, like .deb
or .rpm, this section is for you.
When designing XStatic stuff, we had YOU in mind! :)
But not only you, we also had in mind that there is no packaging system on
Windows and that developers or virtualenv users rather like setuptools,
distribute and pip.
Because of this, we did not want to rely on any mechanism that might be not
available in some scenario - thus, after files are installed, we only use
Python features (like importing from a installed python package, using
__file__ to find out the path/filename, etc.).
You, as a package maintainer are interested in avoiding duplication, so that
if you need to do a security update, you only need to fix in one place.
XStatic-* packages support this. If you do not want to heavily patch some
Python software that uses XStatic ressource packages, you can alternatively
just package the XStatic resource packages for your package system.
In case that would add duplication (because you already have a package that
provides the same static files), you can simply remove the static files below
data/ from the XStatic ressource package and adjust the path/filename so it
points to the files provided by that other package.
E.g. for the XStatic-jQuery package, change::
base_dir = join(dirname(__file__), 'data')
To::
base_dir = '/usr/share/javascript/jquery'
Of course you need to make sure that the files at the location you point to
are the same as the ones the XStatic ressource package provides below the
data/ directory.
In your package dependencies for your repackaged XStatic ressource package
you would then just require (depend on) the package providing these files.
|
