Repository navigation
docs(faq): the definition language is not Python syntax - #297
dimitri-yatsenko wants to merge 4 commits into
Conversation
MilagrosMarin
left a comment
There was a problem hiding this comment.
Verified the claim rather than the wording: declare.py imports pyparsing and builds its own attribute and foreign-key parsers, so "a definition is parsed by DataJoint itself, not by the Python interpreter" is literally true, not just a nice framing. No MATLAB left in faq.md, and this reads consistently with the narrowing in #295.
One editorial note. The Language-agnostic row label now promises something its cell no longer claims — the cell argues only the negative, and says it three ways: "Does not rely on Python syntax; DataJoint parses it, not the Python interpreter, so it is not tied to Python." The prose above already lands the point. Something like "Parsed by DataJoint, not the Python interpreter — nothing in it is Python-specific" keeps the row saying what its label advertises. The same triple-restatement is in the paragraph.
Worth noting on merge order: #295 hasn't landed, so until it does, citation.md on main still reads "Citing DataJoint Python and MATLAB". Merging #295 first keeps the two pages in step.
Unrelated and pre-existing: the link on the edited line ends table-declaration.md/. There are 101 trailing-slash .md/ links across the docs — they pass the checker, so they resolve, but it's the same shape as the dj-platform.svg/ path #278 fixed. Its own sweep, not this PR.
MilagrosMarin
left a comment
There was a problem hiding this comment.
The table cell is exactly right now, and I confirmed aef817c8/1ae51e34 cancel out — no net change hiding in the pair.
The paragraph picked up a claim that doesn't hold, though. It now says neither the data definitions "nor its query operations rely on Python syntax or Python data structures." The definitions half is true and well put. The queries half is wrong on both counts:
- Python syntax — the algebra is Python operator overloading.
expression.pydefines__and__,__sub__,__mul__and__matmul__;a & banda * bare Python expressions, evaluated by the interpreter. - Python data structures —
make_conditiondispatches oncollections.abc.Mapping,numpy.void,pandas.DataFrame,boolandstr.condition.py's own docstring says it converts "(dicts, strings, QueryExpressions) into SQL WHERE clauses".Subject & {"subject_id": 1}is a dict restriction.
A reader disproves the sentence with one line in a notebook, which is why I'd rather catch it here than after it publishes.
The claim that does hold, and is the stronger one anyway: queries are compiled into SQL rather than executed in Python, and the algebra itself is independent of the host language even though its surface syntax is that language's operators. Something like:
The DataJoint Library is implemented in Python, but its data definitions are parsed by DataJoint rather than the Python interpreter, and its queries are compiled into SQL rather than executed in Python. The definition language and the query algebra are both independent of the host language, so the same definitions and operations could be supported by implementations in other languages.
That keeps everything you were reaching for and drops only the part that isn't so.
Follow-up to a review note on PR 295:
faq.mdstill listed MATLAB as a live host language beside the docs' Python-only scope.