docs: Add singleton tables documentation

- Add section 2.5 "Singleton Tables (Empty Primary Keys)" to table-declaration.md
- Update university tutorial with CurrentTerm singleton example
- Remove deprecated `___` separator mention (only `---` is supported)

Related to datajoint/datajoint-python#1341
Closes datajoint/datajoint-python#113

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: dimitri-yatsenko

src/reference/specs/table-declaration.md

@@ -74,15 +74,9 @@ secondary_section
 ---
 ```
 
-or equivalently:
-
-```
-___
-```
-
-- Three dashes or three underscores
-- Separates primary key attributes (above) from secondary attributes (below)
-- Required if table has secondary attributes
+- Three or more dashes
+- Separates primary key attributes (above) from dependent attributes (below)
+- Required if table has dependent attributes
 
 ### 2.4 Line Types
 
@@ -92,6 +86,46 @@ Each non-empty, non-comment line is one of:
 2. **Foreign key reference**
 3. **Index declaration**
 
+### 2.5 Singleton Tables (Empty Primary Keys)
+
+A **singleton table** can hold at most one row. It is declared with no attributes in the primary key section:
+
+```python
+@schema
+class Config(dj.Lookup):
+    definition = """
+    # Global configuration
+    ---
+    setting1 : varchar(100)
+    setting2 : int32
+    """
+```
+
+**Behavior:**
+
+| Operation | Result |
+|-----------|--------|
+| Insert | Works without specifying a key |
+| Second insert | Raises `DuplicateError` |
+| `fetch1()` | Returns the single row |
+| `heading.primary_key` | Returns `[]` (empty) |
+
+**Use cases:**
+
+- Global configuration settings
+- Pipeline parameters
+- Summary statistics
+- State tracking
+
+**Implementation:**
+
+Internally, singleton tables use a hidden `_singleton` attribute of type `bool` as the primary key. This attribute is:
+
+- Automatically created and populated
+- Excluded from `heading.attributes`
+- Excluded from `fetch()` results
+- Excluded from join matching
+
 ---
 
 ## 3. Attribute Definition

src/tutorials/examples/university.ipynb

@@ -53,23 +53,7 @@
    "cell_type": "markdown",
    "id": "cell-schema-intro",
    "metadata": {},
-   "source": [
-    "## Schema Design\n",
-    "\n",
-    "Our university schema models:\n",
-    "\n",
-    "| Table | Purpose |\n",
-    "|-------|--------|\n",
-    "| `Student` | Student records with contact info |\n",
-    "| `Department` | Academic departments |\n",
-    "| `StudentMajor` | Student-declared majors |\n",
-    "| `Course` | Course catalog |\n",
-    "| `Term` | Academic terms (Spring/Summer/Fall) |\n",
-    "| `Section` | Course offerings in specific terms |\n",
-    "| `Enroll` | Student enrollments in sections |\n",
-    "| `LetterGrade` | Grade scale (lookup) |\n",
-    "| `Grade` | Assigned grades |"
-   ]
+   "source": "## Schema Design\n\nOur university schema models:\n\n| Table | Purpose |\n|-------|--------|\n| `Student` | Student records with contact info |\n| `Department` | Academic departments |\n| `StudentMajor` | Student-declared majors |\n| `Course` | Course catalog |\n| `Term` | Academic terms (Spring/Summer/Fall) |\n| `CurrentTerm` | Active registration term (singleton) |\n| `Section` | Course offerings in specific terms |\n| `Enroll` | Student enrollments in sections |\n| `LetterGrade` | Grade scale (lookup) |\n| `Grade` | Assigned grades |"
   },
   {
    "cell_type": "code",
@@ -173,7 +157,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
    "id": "cell-term",
    "metadata": {
     "execution": {
@@ -183,23 +167,8 @@
      "shell.execute_reply": "2026-01-17T06:50:04.029502Z"
     }
    },
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "[2026-01-17 00:50:04,016][WARNING]: Native type 'year' is used in attribute 'term_year'. Consider using a core DataJoint type for better portability.\n"
-     ]
-    }
-   ],
-   "source": [
-    "@schema\n",
-    "class Term(dj.Manual):\n",
-    "    definition = \"\"\"\n",
-    "    term_year : year\n",
-    "    term : enum('Spring', 'Summer', 'Fall')\n",
-    "    \"\"\""
-   ]
+   "outputs": [],
+   "source": "@schema\nclass Term(dj.Manual):\n    definition = \"\"\"\n    term_year : int16\n    term : enum('Spring', 'Summer', 'Fall')\n    \"\"\"\n\n\n@schema\nclass CurrentTerm(dj.Lookup):\n    definition = \"\"\"\n    # Active registration term (singleton)\n    ---\n    -> Term\n    \"\"\""
   },
   {
    "cell_type": "code",
@@ -660,7 +629,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": null,
    "id": "cell-populate-terms",
    "metadata": {
     "execution": {
@@ -670,37 +639,8 @@
      "shell.execute_reply": "2026-01-17T06:50:05.113623Z"
     }
    },
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "339 sections created\n"
-     ]
-    }
-   ],
-   "source": [
-    "# Academic terms 2020-2024\n",
-    "Term.insert(\n",
-    "    {'term_year': year, 'term': term}\n",
-    "    for year in range(2020, 2025)\n",
-    "    for term in ['Spring', 'Summer', 'Fall']\n",
-    ")\n",
-    "\n",
-    "# Create sections for each course-term with 1-3 sections\n",
-    "for course in Course.keys():\n",
-    "    for term in Term.keys():\n",
-    "        for sec in 'abc'[:random.randint(1, 3)]:\n",
-    "            if random.random() < 0.7:  # Not every course every term\n",
-    "                Section.insert1({\n",
-    "                    **course, **term,\n",
-    "                    'section': sec,\n",
-    "                    'auditorium': f\"{random.choice('ABCDEF')}\"\n",
-    "                                  f\"{random.randint(100, 400)}\"\n",
-    "                }, skip_duplicates=True)\n",
-    "\n",
-    "print(f\"{len(Section())} sections created\")"
-   ]
+   "outputs": [],
+   "source": "# Academic terms 2020-2024\nTerm.insert(\n    {'term_year': year, 'term': term}\n    for year in range(2020, 2025)\n    for term in ['Spring', 'Summer', 'Fall']\n)\n\n# Set the current registration term (singleton - only one row allowed)\nCurrentTerm.insert1({'term_year': 2024, 'term': 'Fall'})\nprint(f\"Current term: {CurrentTerm.fetch1()}\")\n\n# Create sections for each course-term with 1-3 sections\nfor course in Course.keys():\n    for term in Term.keys():\n        for sec in 'abc'[:random.randint(1, 3)]:\n            if random.random() < 0.7:  # Not every course every term\n                Section.insert1({\n                    **course, **term,\n                    'section': sec,\n                    'auditorium': f\"{random.choice('ABCDEF')}\"\n                                  f\"{random.randint(100, 400)}\"\n                }, skip_duplicates=True)\n\nprint(f\"{len(Section())} sections created\")"
   },
   {
    "cell_type": "code",
@@ -2369,6 +2309,14 @@
     "all_a"
    ]
   },
+  {
+   "cell_type": "code",
+   "id": "20yuzwslxgm",
+   "source": "# Sections available in the current term (using singleton)\nSection & CurrentTerm",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
   {
    "cell_type": "markdown",
    "id": "cell-proj-intro",
@@ -6548,4 +6496,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}