Bug#758402: ITP: python-xstatic-jquery.quicksearch -- jQuery.quicksearch XStatic support
Thomas Goirand wrote:
> On 08/17/2014 10:29 PM, Justin B Rye wrote:
>> Thomas Goirand wrote:
>>> Thanks for this message. I would welcome indeed any change to this long
>>> description, reviewed by the d-l-english team!
>>
>> Well, I'd like to, but so far I don't really understand it. I don't
>> even know what it means by "static files". As opposed to what?
>
> As opposed to dynamic content. For example:
> - javascript
> - .css
> - .png
>
> are all static files, and not scripts. This is what XStatic provides.
When you say "not scripts" you mean "not the Python code of your
actual webapp", right? Oh well, I get it now. My confusion was
because when a package description says it contains "static files",
that essentially boils down to "any actual files at all", since
obviously it can't provide content for $DOCROOT/dynamic/!
>>> I do believe this is relevant. The point of the XStatic packages is that
>>> they are available using "pip install", which make them universal. This
>>> is a very good "selling point" for Python developers, and will push them
>>> to use XStatic rather than embedding static files directly in their
>>> python module/app.
>>
>> I'm sure it's an interesting fact about XStatic, and therefore may
>> belong in the package description for python-xstatic. But how is it
>> useful information for people trying to decide whether to install
>> python-xstatic-jquery.quicksearch? It seems to amount to "this
>> software is also available as something that isn't a Debian package",
>> and that's true of pretty much anything in the archives.
>
> The point is that they will have an API to find out what is the location
> of the jquery.quicksearch in the system. And this API will work on every
> operating system using packages (if they are available), or by
> downloading the XStatic package using "pip install
> xstatic-jquery.quicksearch" within the Python virtualenv.
Yes, this explains why my imaginary developer on BeOS would want it -
or even developers on Debian who want to work entirely in Python eggs
and bypass APT. But it doesn't quite explain why there's a Debian
package.
>> Meanwhile there's literally no description whatsoever of the
>> functionality of jQuery.quicksearch!
>
> The package depends on libjs-quicksearch. This is where you have the
> correct description, and that's where I expect users will read. Do you
> think the description of jquery.quicksearch should be copied there too?
Seeing it as a sort of dependency shim package, maybe you could cut
the entire thing right down to:
This package integrates jQuery.quicksearch (see libjs-quicksearch)
into the XStatic system (see python-xstatic).
> By the way, python-xstatic-* packages aren't directly useful for the
> final users, they will only be dependencies of Python applications, and
> in my case, the OpenStack dashboard (eg: the Horizon web GUI).
Well, the final users of webapps might not even own a computer! But
for the sake of Debian users scanning the list of newly available
devel packages, the ideal description would let them see at a glance
whether this is useful to them.
[...]
>> But I definitely don't yet understand how XStatic renders a collection
>> of files "easily usable on all operating systems with any package
>> management system". Sure, bundling files into a Python egg might make
>> them accessible via a Python egg installer, but that's not the same
>> thing as making it possible to install them with APT.
>
> The point of XStatic is to avoid developers to embed static files of
> libraries (often: javascript libraries) directly in their Python
> application, which is a security disaster from a distribution stand
> point. A Python developer will simply make his application "require"
> (which is the Python language to say "depends") the XStatic python
> module. If the developer works with pip, then it will automatically "pip
> install xstatic-jquery.quicksearch" for example, which will go in the
> virtualenv (which is a kind of chroot-like stuff specific to Python, if
> you like).
Yes, so developers using pip get to pull in Python xstatic-foo modules
as dependencies. I see that. But requiring xstatic-foo can't pull in
a Debian package; and if on the other hand I'm using Debian package
dependencies, what's the benefit of depending on python-xstatic-foo
instead of libjs-foo direct?
Does python-xstatic-foo maybe set up the libjs-foo libraries so that
they're pulled into a virtualenv (for some reason) instead of being
used directly out of the system libraries? No, apparently not...
Oh, no, I see: even if pip can't *pull in* a .deb, a previously
installed .deb might still contain the module in an appropriate way to
satisfy the dependency. Perhaps even for people running pip within a
virtualenv?
> When in a distribution like Debian, the
> python-xstatic-jquery.quicksearch does *not* embed the library. It only
> Depends: on the libjs-jquery.quicksearch (which I packaged separately),
> and "points" to it (eg: in the package, I have patched upstream code
> "BASE_DIR" configuration variable, which is what upstream recommends).
>
> So XStatic stuff are really made for better integration within
> distributions.
>
>> So the thing to do is arrange for the package that contains your
>> Python software to depend on the package that contains that JavaScript
>> library. Right? Oh, no, of course, you can't do that because you're
>> not on Debian, so your packaged Python doesn't have any way of
>> depending on JavaScript - other than directly including the files,
>> which is nasty. Or... putting them in a *fake* Python package? Aaah!
>> Maybe this is beginning to make sense now...
>
> I think you got it! Except that it's not really a "fake" python package,
> it's a real one which is available from PyPi... :)
>
> So, these Python packages really include the javascript, though the
> Debian resulting python .deb will not.
>
>>> By having static files in packages, it is also easier to build
>>> virtual envs,
>>
>> Borderline ungrammatical. And isn't it "virtualenvs"? (Or "virtual
>> environments", but that's bad because it sounds as if it means what it
>> says.)
>
> virtual envs, or virtualenvs, are in the common Python dictionary. This
> should stay as-is. Anyone who knows a bit about Python knows (or heard
> about) virtualenvs.
The word in the jargon dictionary is <virtualenv>; that's why I
recommend correcting it *to* "virtualenvs". There's no such thing in
the Python dictionary as an "env".
(My peeve with the term "virtual environment" stems from the fact that
your computer is already running one of those before it gets past the
bootloader. A virtualenv doesn't make things any more virtual
than they already were... so it's best to treat it as an arbitrary
string.)
>>> support linux/bsd/... distribution package maintainers and even
>>> windows installs using the same mechanism.
>>
>> All the above is the blurb for the XStatic framework, and doesn't
>> belong in the python-xstatic-jquery.quicksearch package description
>> unless that Debian package really does make it easier to support
>> Windows installs. A deverbosified version could go in the package
>> description for python-xstatic, but I'd prefer to start from somewhere
>> else.
>
> Yeah, that's bad! Feel free to provide something better.
>
>> XStatic (see python-xstatic) is a Python web development tool for
>> bundling sets of required data files from external non-Python
>> projects into Python packages that your app can depend on portably.
>
> Very good, thanks! Should that be it for all the python-xstatic-* packages?
If I can work out the final wrinkle ("why would you Debianise it?")
then I might add a couple of words, but that would be more or less it.
>> Then the ...-jquery.quicksearch package should end with a description
>> of this JS library, or at least a pointer to libjs-jquery.quicksearch.
>
> Which of the 2 options would you recommend?
If you don't want the ultra-short version I suggested above you could
have the generic XStatic paragraph followed by:
This package integrates jQuery.quicksearch (see libjs-quicksearch)
into the XStatic system.
It leaves the part I don't understand unexplained, but it may have
shrunk to the point where that doesn't matter.
>> So the point of this package isn't that you'd want to *install* it -
>> after all, you could just do "apt install libjs-jquery.quicksearch".
>> The point is to make it possible for your Python modules to depend on
>> this Python module, because that approach lets you install your webapp
>> on BeOS like all the cool kids are doing and have it pull in all the
>> appropriate data files. Except... why has it been Debianised? Nope,
>> this still isn't quite making sense to me.
>
> The debianization part is the "Depends: libjs-jquery.quicksearch", and
> the fact that xstatic/pkg/jquery_quicksearch/__init__.py has been
> patched to point to /usr/share/javascript/jquery.quicksearch. It also
> reports the version of libjs-jquery.quicksearch.
>
> I hope now that everything make sense, and that you can write back a
> single new reply so that we can close this case! :)
Let's see: the Debian package can't be pulled in by pip, but it can
satisfy pip dependencies, which improves portability in aspects of the
workflow I probably don't need to know about. If it also provides
hooks to make virtualenv setups work more smoothly, might that deserve
a couple of words of explanation?
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: