Skip to content

Commit 7abeef7

Browse files
docs: Improve extend() docstring formatting
- Use bullet lists for requirements - Use bold for section headers - Use >>> doctest style for examples - Use inline code formatting for identifiers Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 58e8d13 commit 7abeef7

File tree

1 file changed

+16
-17
lines changed

1 file changed

+16
-17
lines changed

src/datajoint/expression.py

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -442,34 +442,33 @@ def extend(self, other, semantic_check=True):
442442
Extend self with attributes from other.
443443
444444
The extend operation adds attributes from `other` to `self` while preserving
445-
self's entity identity. It is semantically equivalent to `self.join(other, left=True)`
445+
self's entity identity. It is semantically equivalent to ``self.join(other, left=True)``
446446
but expresses a clearer intent: extending an entity set with additional attributes
447447
rather than combining two entity sets.
448448
449-
Requirements:
450-
self → other: Every attribute in other's primary key must exist in self.
451-
This ensures:
452-
- All rows of self are preserved (no filtering)
453-
- Self's primary key remains the result's primary key (no NULL PKs)
454-
- The operation is a true extension, not a Cartesian product
449+
**Requirements**: ``self → other`` (self determines other). Every attribute in
450+
other's primary key must exist in self. This ensures:
455451
456-
Conceptual model:
457-
Unlike a general join (Cartesian product restricted by matching attributes),
458-
extend is closer to projection—it adds new attributes to existing entities
459-
without changing which entities are in the result.
452+
- All rows of self are preserved (no filtering)
453+
- Self's primary key remains the result's primary key (no NULL PKs)
454+
- The operation is a true extension, not a Cartesian product
455+
456+
**Conceptual model**: Unlike a general join (Cartesian product restricted by
457+
matching attributes), extend is closer to projection—it adds new attributes
458+
to existing entities without changing which entities are in the result.
460459
461460
Examples
462461
--------
463-
Session determines Trial (session_id is in Trial's PK), but Trial does NOT
464-
determine Session (trial_num not in Session).
462+
Session determines Trial (``session_id`` is in Trial's PK), but Trial does NOT
463+
determine Session (``trial_num`` not in Session).
465464
466-
Valid: extend trials with session info::
465+
Valid - extend trials with session info:
467466
468-
Trial.extend(Session) # Adds 'date' from Session to each Trial
467+
>>> Trial.extend(Session) # Adds 'date' from Session to each Trial
469468
470-
Invalid: Session cannot extend to Trial::
469+
Invalid - Session cannot extend to Trial:
471470
472-
Session.extend(Trial) # Error: trial_num not in Session
471+
>>> Session.extend(Trial) # Error: trial_num not in Session
473472
474473
Parameters
475474
----------

0 commit comments

Comments
 (0)