Documentation issues

[Ed]

As I go through brython docs again, I notice some things that aren't clear to me.  Perhaps it's worth discussing whether docs should be clarified.

For instance, the page Query String says this:

Query string

browser.document supports the attribute query, that returns the query string as an object with the following attributes and methods :

• document.query[key] : returns the value associated with key. If a key has more than one value (which might be the case for SELECT tags with the attribute MULTIPLE set, or for <INPUT type="checkbox"> tags), returns a list of the values. Raises KeyError if there is no value for the key

To me, query string is the portion of the url after ? that holds query params.  Output of urlparse reflects this usage.  It's part of the page url and invariant across the DOM.

On this brython doc page, query string appears to be something else.  INPUT and SELECT tags don't change the page url.  Why does document.query reference them?  Is document.query reading values from the DOM not from query string?  Does document.query ['foo'] read values from an element such as <input id="foo"> on the page?

Some changes to docs would help:

• If query string means query parameters in page url, then language about INPUT and SELECT should be removed.  Examples should be urls, perhaps like this: http://localhost?foo=bar for single value and http://localhost?foo=bar&foo=rab for multiple values.
• If query string means querying DOM elements for values then perhaps the term "query string" should be changed here, as query string generally means something different.

[Denis Migdal]

Indeed, the string is a "selector", not a "query".
I assume this is: document.query[selector]


--
You received this message because you are subscribed to the Google Groups "brython" group.
To unsubscribe from this group and stop receiving emails from it, send an email to brython+u...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/brython/CAF1%3DpDkUAnQrSfxRRcgSF4r2YBk4L043qoXHxwrNK5OFFnLb1w%40mail.gmail.com.

[Ed]

Ok so it's like document.querySelector in js but returns values instead of element nodes.  Then "query string" is the misleading part.

Perhaps this text would be better:

browser.document supports the attribute query, that queries DOM elements matching a selector string key with the following attributes and methods :

Renaming "key" to "selector" would also help.

I would know this if I ever used query, but I use js DOM methods instead of their brython equivalents.  Easier to find info on places like MDN and stackexchange when things don't work as expected.  And makes code more portable in case I ever have to switch to another python interpreter one day (hopefully not).  Just a personal choice.

To view this discussion visit https://groups.google.com/d/msgid/brython/CAFr00W7rQ0sbgxtSjPSB%2BusbFLKKOqL7cTi%3DF8TiWCBuT88xyQ%40mail.gmail.com.

[Pierre Quentel]

I agree that the redaction is not clear, but the idea is that if an HTML page is the attribute action of a form

<form action="query_test.html" method="get">

<input name="foo">

</form>

then in Brython code inside query_test.html you get the value of the field named "foo" by

document.query['foo']

[Denis Migdal]

Wait I'm confused.

Is this a selector (get the value from the DOM) or an URL search param (get the value from the URL search) ?

To view this discussion visit https://groups.google.com/d/msgid/brython/2f3eb8b7-9f96-4647-accf-0577ba53d279n%40googlegroups.com.

[Ed]

As Pierre said, it's url params (what js calls URL.search and python calls url.query).

Verify by going to to https://brython.info/tests/console.html?lang=en and do:

>>> from browser import document as doc

>>> doc.query ['lang']

'en'

There is no DOM node on that page with id="lang" or class="lang" or even tag <lang>.  query reads from document.location.

In which case the references to INPUT and SELECT should be removed.

Pierre - such elements may be one possible way to generate query params in a URL.  But it's far from the only way, and I would say not the most common way these days.

More importantly, current text is confusing (as this email chain demonstrates).  Elements on a page have no connection with page url.  The text makes it sound like it queries INPUT and SELECT elements on the current page, which is not the case.

It would be much clearer to use URLs as examples without mentioning INPUT or SELECT, like this: 

http://localhost?foo=bar for single value and http://localhost?foo=bar&foo=rab for multiple values

To view this discussion visit https://groups.google.com/d/msgid/brython/CAFr00W7vB%3Diy-Jn6R5424z6yQzTxeu1me9t13cXQYWF1OHSKuQ%40mail.gmail.com.

[Pierre Quentel]

I have updated the documentation in commit https://github.com/brython-dev/brython/commit/c4695a973236beb78ec810509efd668ea29406b6, hope it's more clear this way